home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr47 / altqb553.zip / TOOLBOX.DOC < prev   
Text File  |  1993-05-08  |  175KB  |  4,485 lines

  1.  
  2.           Assembly-Language Toolbox for VisualBASIC DOS
  3.           ─────────────────────────────────────────────
  4.                        By Christy Gemmell
  5.  
  6. The Assembly-Language Toolbox started life, five years ago, as a simple
  7. collection of useful routines for adding zip to my QuickBASIC programs.
  8. They weren't just pretty faces however. In order to qualify, the Toolbox
  9. routines had to work reliably with real-life commercial applications, the
  10. ones on which my living depended. This made for pretty tough testing, but
  11. those which did survive were, in consequence, fast, robust and, above all,
  12. able to do the job. They are, in fact, doing so in Accountants and Stock-
  13. broker's offices, all over my native Great Britain.
  14.  
  15. A colleague uploaded a copy of the Toolbox onto a local BBS (Electronic
  16. Bulletin Board) and suddenly I started getting letters and phone calls
  17. from complete strangers asking for a copy of the latest version. Nearly
  18. everyone who called had suggestions of their own, remarking; "You know, if
  19. only the Toolbox had this, it would be really good...".
  20.  
  21. Wherever practicable, the good ideas (and some were brilliant) were turned
  22. into assembler code and added to the collection. Almost before I realised
  23. what was happening, the Assembly-Language Toolbox was on the Shareware
  24. circuit and being used by programmers in Europe, the USA, Canada,
  25. Australia and Japan. By December 1990 it had gone through four 'official'
  26. releases and a dozen or more unofficial ones.
  27.  
  28. Release Five comes in two flavours; one for QuickBASIC 4 and the other for
  29. Microsoft's BASIC 7 Professional Development System. The QB4 version
  30. covers QuickBASIC 4.0, 4.5 and BASIC 6 while the PDS version is compatible
  31. with BASIC 7, 7.1 and Extended QuickBASIC (QBX). In either version the
  32. routines are provided both as stand-alone libraries and as Quick Libraries
  33. for use in the programming environment.
  34.  
  35. With the advent of Microsoft's VisualBASIC for DOS, we have introduced
  36. a third version of the Toolbox, designed specifically for this compiler.
  37. ALTVBDOS Release 1.00 includes all the routines from ALTQUICK ver 5.50, 
  38. repackaged for VisualBASIC for DOS.
  39.  
  40. Using the Toolbox is easy. All the routines are written to look like
  41. standard QuickBASIC SUB programs and FUNCTION procedures. All you have to
  42. do is choose the ones you want to use in your current program and paste
  43. the appropriate DECLARE statements (a full set is provided) into the
  44. source code. If you need to output large quantities of text to the screen
  45. at high speed, for example, just copy the following line from ALTQUICK.DEF.
  46.  
  47. DECLARE SUB FastPrint (BYVAL Row%, BYVAL Col%, Text$, BYVAL Attribute%)
  48.  
  49. Then, if you are running in the QuickBASIC environment, you should load
  50. the Quick Library with the command:
  51.  
  52.     QB yourprog.bas /L altvbdos.qlb
  53.  
  54. Thereafter you can call FastPrint, exactly as you would any other
  55. QuickBASIC SUB program, for example like this:
  56.  
  57.     FastPrint 25, 34, "Hello World!", 48
  58.  
  59. which will print 'Hello World!' in the middle of the 25th screen row
  60. displaying it in black characters on a cyan background (if you have a
  61. colour monitor). Notice that, since a DECLARE statement has been used, you
  62. don't need to place parentheses around the argument list and that even the
  63. CALL statement is unneccessary. Used in this way, Toolbox routines become
  64. actual extensions to the QuickBASIC language.
  65.  
  66. The same DECLARE statements can still be used when you compile your
  67. programs from the DOS command line. In this case, however, you must link
  68. the compiled program to ALTQUICK.LIB, the stand-alone library, with
  69. something like this:
  70.  
  71.     LINK yourprog,,,altquick.lib;
  72.  
  73. The QuickBASIC Linker will only extract, from ALTQUICK.LIB, those modules
  74. which are explicitly named by DECLARE statements in the source file. This
  75. ensures that your programs are not burdened with unneccessary code.
  76.  
  77. Toolbox routines do not require the BASIC runtime module to be present.
  78. You can use them to produce completely stand-alone application programs
  79. which can be distributed commercially.
  80.  
  81. As its name implies, the core routines in the Assembly-Language Toolbox
  82. are written in pure Intel 80x86 assembler. Because of this they are small,
  83. efficient and blindingly fast. Moreover, since any internal variables are
  84. stored in a routine's own code segment, your program does not have to
  85. share any of it's precious data space with the library.
  86.  
  87. Christy Gemmell                                             January 1993
  88.  
  89. ──────────────────────────────────────────────────────────────────────────
  90.  
  91. The ShareWare version of the Assembly-Language Toolbox for QuickBASIC is
  92. provided, free of charge, to any QuickBASIC programmer who can find a use
  93. for it. You are encouraged to copy it, upload it to Electronic Bulletin
  94. Boards or pass it on to friends, provided only that you make no charge for
  95. doing so and that all the files on the disk are preserved intact. You may
  96. freely include Toolbox routines in your own programs, both for private use
  97. and for commercial distribution, without payment to the author.
  98.  
  99. The Professional version of the Toolbox, available to Registered Users,
  100. comes complete with all the source code, object modules for building your
  101. own custom libraries and many additional features. Hotline support is also
  102. included, at no extra charge.
  103.  
  104. ─────Registration and Support──────────────────────────────────────────────
  105.  
  106. U.K. and Europe:        £25.00 (including postage and packing)
  107.  
  108. Christy Gemmell         Apt.13, Beckville Building
  109.                         17 Glebe street
  110.                         Leicester LE2 0JR
  111.                         United Kingdom
  112.                         
  113.                 Tel:    (044)-0533-540720
  114.  
  115. U.S.A. and Canada:      $47.50 (Including shipping)
  116.  
  117. James Kreyling          CPC Consulting Company
  118.                         1217 Crescent Dive
  119.                         Smithfield, Va. 23430
  120.                         U.S.A.
  121.  
  122.                 Tel:    (804)-357-9190 (Voice and FAX)
  123. or from Club-PC BBS:    (804)-357-0357 (8-N-1)
  124.  
  125. Note:   When ordering the Toolbox please specify if for QuickBASIC 4.5,
  126.         BASIC 7.1 PDS or VB DOS and the floppy disk format you require.
  127.  
  128. ─────About the author─────────────────────────────────────────────────────
  129.  
  130. Christy Gemmell, the author of this package, is also major author of the
  131. definitive textbook on QuickBASIC programming, the QuickBASIC BIBLE, which
  132. is published by Microsoft Press, in association with the Waite Group, at
  133. £24.95 ($27.95 US) ISBN 1-55615-262-0. Selected as Computer Book of the
  134. Month by Jerry Pournelle in the March 1991 issue of BYTE, its thousand
  135. pages are packed with information, tips and example programs which you
  136. wont find anywhere else.  Look out for it in your local bookstore.
  137.  
  138. The Assembly-Language Toolbox for QuickBASIC is used by thousands of
  139. programmers in Great Britain, Europe, the USA and Canada, Australasia and
  140. Japan, to build fast and powerful QuickBASIC programs. It has been shown
  141. at COMDEX and was featured in the November 1990 issue of BYTE magazine.
  142.  
  143. ───────────────────────────────────────────────────────────────────────
  144.  
  145.                 TOOLBOX FUNCTIONS AND PROCEDURES
  146.  
  147. This is a full, alphabetical, listing of the routines in the Assembly
  148. Language Toolbox which can be called directly by QuickBASIC programs>
  149.  
  150.  
  151. ATTRIB
  152.  
  153. This function returns the directory attributes of the specified file.
  154.  
  155. DECLARE FUNCTION Attrib% (FileSpec$)
  156.  
  157. FileSpec$ is the name of the file whose directory entry is to be tested.
  158. You should include the full pathname (including drive letter if necessary)
  159. if the file is not in the current directory.
  160.  
  161. The returned attribute value is bit-encoded as follows:
  162.  
  163.    Bit     Meaning (if set)
  164. ─────────────────────────────────────────────────────
  165.     0      Read-only     (file is Read/Write if zero)
  166.     1      Hidden
  167.     2      System
  168.     3      Volume label
  169.     4      Subdirectory
  170.     5      Archive
  171.     6      Not used
  172.     7      Shareable     (Novell Networks only)
  173. ─────────────────────────────────────────────────────
  174.  
  175. The ToolBox procedures; HIDE, SECURE and SHARE (see below) can be used to
  176. modify the attributes of a file.
  177.  
  178.  
  179. ATTRIBUTE
  180.  
  181. Converts standard MS-DOS foreground and background COLOR values into
  182. their equivalent display attribute number.
  183.  
  184. DECLARE FUNCTION Attribute% (BYVAL Fore%, BYVAL Back%)
  185.  
  186. Legal values:    Fore% = 0 - 31
  187.                  Back% = 0 - 15
  188.  
  189. The Assembly-Language Toolbox provides several routines which allow  your
  190. QuickBASIC programs to write text directly to the display with an
  191. attribute which you supply. For an explanation of display attributes, see
  192. the topic file COLOURS.HLP supplied with the Assembly-Language Toolbox
  193. demonstration program.
  194.  
  195. Note that the QuickBASIC COLOR statement only allows values of 0-7 for
  196. background colours. Toolbox display routines, however, accept the full
  197. range, using values of 8-15 to produce blinking or high-intensity
  198. background colours. See BLINKING (below) for a routine which allows
  199. you to select between these two modes.
  200.  
  201.  
  202. BACKFILL
  203.  
  204. This procedure changes the display attributes of the characters contained
  205. within the screen rectangle you specify, without overwriting the text
  206. itself.
  207.  
  208. DECLARE SUB BackFill (BYVAL R%, BYVAL C%, BYVAL H%, BYVAL W%, BYVAL A%)
  209.  
  210. R% = Top-left row of the rectangle to be coloured.
  211. C% = Top-left column of the rectangle.
  212. H% = Height of the rectangle in rows.
  213. W% = Width of the rectangle in columns.
  214. A% = Display attribute to use for colouring.
  215.  
  216.  
  217. BARMENU
  218.  
  219. Creates and operates a menu orientated horizontally on the screen row
  220. specified. The calling program must supply :
  221.  
  222. Row%        =   The screen row on which the menu bar will appear.
  223. Atr%        =   The display attribute or colour for the menu bar.
  224. Opt%        =   Number of options available for selection.
  225. Menu$()     =   String array containing selection list. Menu$(0) should
  226.                 be set to a string of ASCII characters, corresponding to
  227.                 the initial or key letter of each option in the list.
  228.                 Insert a space at the appropriate position of an option
  229.                 to be disabled. In the remaining option strings an
  230.                 ampersand '&' indicates that the next character is the
  231.                 Hotkey to be highlighted for that option.
  232. Bar%        =   The menu selection to be highlighted on entry into the
  233.                 procedure.
  234. Nxt%        =   If set, this flag just causes the menu to be refreshed
  235.                 without pausing for a selection from the user. This is
  236.                 used to handle presses on the Right or Left Arrow keys
  237.                 in the Pull-Down Menu procedure.
  238. Ctx%        =   If set, this flag indicates that context-sensitive help
  239.                 is available, in which case ...
  240. Tpc$        =   The root name of the Topic file to be displayed if the
  241.                 user presses <F1> for help. The current selection number
  242.                 is appended to this to produce the actual filename.
  243.  
  244.                 eg, if Tpc$ = "CONFIG" and Bar% = 3
  245.                 
  246.                 HelpMate (see TOOLBOX.DOC) will look for a Topic file
  247.                 named CONFIG3.HLP.
  248. Mouse%      =   If set, this flag indicates that a mouse is installed
  249.                 and can be used to make selections.
  250. HotKeys%    =   If set, this flag allows hotkeys to go directly to a
  251.                 selection without you having to press <ENTER> as well.
  252.  
  253. DECLARE SUB BarMenu (Row%, Atr%, Opt%, Menu$(), Bar%, Nxt%, Ctx%,_
  254.                      Topic$, Mouse%, HotKeys%)
  255.  
  256. On completion the procedure returns with the following variable set:
  257.  
  258. Bar%        =   Number of selection made by user. If zero then the
  259.                 <Escape> key was pressed to abort the procedure
  260.                 without making a selection.
  261.  
  262. VERMENU (see below) is a similar procedure which operates a vertically
  263. orientated point-and-shoot type menu.
  264.  
  265. See the source code of DEMON.BAS, the Toolbox demonstration program, for
  266. examples of BARMENU and VERMENU in use.
  267.  
  268.  
  269. BINDEC
  270.  
  271. Translates a string of binary digits to their long integer decimal
  272. equivalent.
  273.  
  274. DECLARE FUNCTION BinDec& (Binary$)
  275.  
  276.  
  277. BITSHL
  278.  
  279. Shifts all the bits of a long-integer number the specified number
  280. of places to the left.  This effectively multiplies the number by
  281. 2 ^ the number of places.
  282.  
  283. DECLARE SUB BitShl (Number&, Count%)
  284.  
  285. Number& =   The 32-bit number to be shifted 
  286.             (-2147483648 to 2147483647)
  287. Count%  =   The number of places to be shifted (1-31)
  288.  
  289.  
  290. BITSHR
  291.  
  292. Shifts all the bits of a long-integer number the specified number
  293. of places to the right.  This effectively divides the number by
  294. 2 ^ the number of places.
  295.  
  296. DECLARE SUB BitShr (Number&, Count%)
  297.  
  298. Number& =   The 32-bit number to be shifted 
  299.             (-2147483648 to 2147483647)
  300. Count%  =   The number of places to be shifted (1-31)
  301.  
  302.  
  303. BITRESET
  304.  
  305. Clears the specified bit (0-15) of the integer number supplied.
  306.  
  307. DECLARE SUB BitReSet (Number%, Bit%)
  308.  
  309.  
  310. BITSET
  311.  
  312. Sets the specified bit (0-15) in the integer number supplied to 1.
  313.  
  314. DECLARE SUB BitSet (Number%, Bit%)
  315.  
  316.  
  317. BITTEST
  318.  
  319. Returns logical TRUE (-1) if the bit (0-15) of Number% is set and FALSE
  320. (zero) if the bit is clear.
  321.  
  322. DECLARE FUNCTION BitTest% (Number%, Bit%)
  323.  
  324.  
  325. BLINKING
  326.  
  327. Toggles between blinking and high-intensity background colours
  328.  
  329. DECLARE SUB Blinking (BYVAL Switch%)
  330.  
  331. Switch% = 0         Turn background blink off/enable high intensity
  332.                     background colours.
  333.  
  334.         = non-zero  Enable background blinking/disable high intensity
  335.                     background colours
  336.  
  337. The QuickBASIC COLOR statement only recognises values of 0-7 for its'
  338. second parameter. Unlike the foreground, you cannot select blinking or
  339. high-intensity colours for the display backgound. The screen attribute
  340. parameter used with Toolbox routines such as FASTPRINT, however, do
  341. permit a background colour component in the range 0-15.
  342.  
  343. Normally, values between 8-15 will produce blinking backgrounds, but
  344. BLINKING allows you to turn the the blink off, forcing the background
  345. colour into high intensity mode. With blinking disabled you can use
  346. the full range of colours which are available to the foreground.
  347.  
  348. See ATTRIBUTE (above) for a function that calculates display attributes
  349. from the foreground and background colours you supply
  350.  
  351. Note:   This routine only works on systems with EGA, VGA and MCGA
  352.         display adaptors. Users of CGA adaptors, however, can get
  353.         the same effect by using the statement:  OUT &H3D8, 9
  354.  
  355. If you turn blinking off, remember to re-enable it before your program
  356. ends. Otherwise high-intensity backgrounds will remain in effect until
  357. another program resets the video card or you switch your computer off.
  358.         
  359.  
  360. CAPITAL
  361.  
  362. Converts all alphabetic characters in a string to lower-case,
  363. except for the first character of each word, which is forced
  364. to upper-case.
  365.  
  366. DECLARE FUNCTION CapItal$ (Original$)
  367.  
  368. This function is designed for use in printing address labels
  369. and can correctly identify and format proper surnames like
  370. 'McLaughlin'.
  371.  
  372.  
  373. CAPSLOCK
  374.  
  375. Toggles CAPS LOCK on or off or, alternatively, reads the current CAPS LOCK
  376. key setting.
  377.  
  378. DECLARE FUNCTION CapsLock% (BYVAL Switch%)
  379.  
  380. Switch% = 0  Turns CAPS LOCK off
  381.         = 1  Turns CAPS LOCK on
  382.  
  383. Any other value just returns the current CAPS status as a logical value
  384. where -1 (TRUE) means that CAPS LOCK is on and 0 (FALSE) means that CAPS
  385. LOCK is off.
  386.  
  387.  
  388. CGACOPY
  389.  
  390. Copies a CGA screen to or from a user-supplied string.
  391.  
  392. DECLARE SUB CgaCopy (BYVAL Switch%, Buffer$)
  393.  
  394. SWITCH%     Direction of copy   0 = copy screen to string
  395.                                 1 = copy string to screen
  396.  
  397. BUFFER$     String variable to hold the screen image, must be at least
  398.             16384 characters long or the call will fail. 
  399.  
  400. Note:       If you are using QuickBASIC 4 or 4.5, do not pass a fixed-
  401.             length string to this routine. Only variable-length strings
  402.             will work safely.
  403.  
  404. The QuickBASIC PCOPY statement is very useful for storing screen pages in
  405. memory, so that they can be kept out of sight until needed. Unfortunately
  406. it only works in text modes or, on computers with EGA or VGA video cards,
  407. in SCREEN modes 7 to 12. This routine, on the other hand, works only in
  408. the CGA display modes (SCREENs 1 and 2), it provides a useful alternative
  409. to the PCOPY statement for use with medium-resolution screens.
  410.  
  411. See also MCGACOPY for a version that can be used with SCREEN 13 displays.
  412.  
  413.  
  414. CGASCROLL
  415.  
  416. Scrolls a rectangular portion of a SCREEN 1 (320 x 200 4-colour) display
  417. four pixels to the left or to the right, wrapping the pixels which are 
  418. scrolled out at the end round to the beginning again.
  419.  
  420. DECLARE SUB CgaScroll (BYVAL xLoc%, BYVAL yLoc%, BYVAL xPixels%,_
  421.                        BYVAL yPixels%, BYVAL Direction%)                 
  422.  
  423. XLOC%       The horizontal (X) co-ordinate of the top-left corner of
  424.             the rectangle to be scrolled.
  425.  
  426. YLOC%       The vertical (Y) co-ordinate of the top-left corner of
  427.             the rectangle to be scrolled.
  428.  
  429. XPIXELS%    The width (in pixels) of the rectangle to be scrolled.
  430.  
  431. YPIXELS%    The height (in pixels) of the rectangle to be scrolled.
  432.  
  433. DIRECTION%  The direction in which the rectangle contents are to be
  434.             scrolled (0 = Left, 1 = Right).
  435.  
  436. Co-ordinates are in the ranges:  X >= 0 <= 319, Y >= 0 <= 199
  437.  
  438. X co-ordinates are aligned to the nearest byte (1 byte = 4 pixels).
  439.  
  440.  
  441. CGATEXT
  442.  
  443. Writes characters to the screen in the 320 x 200 4-colour graphics mode.
  444.  
  445. DECLARE SUB CgaText (BYVAL xLoc%, BYVAL yLoc%, Text$,_
  446.                      BYVAL Attr%, BYVAL Scale%)
  447.  
  448. This routine provides a convenient way of displaying text in SCREEN 1
  449. without having to bother about loading external font files. It uses the
  450. standard ROM-BIOS character definition tables built into your display
  451. adaptor, but allows you to scale them up to eight times normal size and to
  452. specify any combination of foreground and background colours.
  453.  
  454. XLOC%       The horizontal co-ordinate of the top left hand pixel
  455.             from which the text will begin (0 - 319)
  456.  
  457. YLOC%       The vertical co-ordinate of the top left hand pixel
  458.             from which the text will begin (0 - 199)
  459.  
  460. TEXT$       The string of text to be displayed (up to 63 characters).
  461.  
  462. ATTR%       The colour (or display attribute in monochrome modes) to
  463.             be given to the text. This is calculated by the formula:
  464.  
  465.             Colour% = (Background% * 256) + Foreground%
  466.  
  467.             Foreground and Background values are in the range 0 - 3
  468.  
  469. SCALE%      The character size of the text to be displayed. This ranges
  470.             from 1 to 8, where 1 is standard 40-column text and where 8
  471.             multiplies the character size by eight on both the horizontal
  472.             and vertical axes.
  473.  
  474. CGATEXT can handle both byte-aligned and non byte-aligned characters. The
  475. x, y co-ordinates you supply do not need to correspond to a row, column
  476. character cell in SCREEN 0, the alphanumeric mode. The complete ASCII set
  477. is supported, but to display foreign symbols and box-drawing characters on
  478. a CGA adaptor you must have the DOS GRAFTABL utility loaded.
  479.  
  480. Since CGATEXT does not support clipping, to ensure a clean display you
  481. must ensure that the text to be output fits within the current screen
  482. boundaries.
  483.  
  484. See also VGATEXT for displaying characters in SCREENs 7-12 and MCGATEXT
  485. for displaying characters in SCREEN 13.
  486.  
  487.  
  488. CENTRE
  489.  
  490. Centres the string supplied within an empty string of specified width.
  491.  
  492. DECLARE FUNCTION Centre$ (Text$, MaxWidth%)
  493.  
  494. This function is called by the VERMENU routine (see below) to centre the
  495. title of a pull-down menu within the window it refers to.
  496.  
  497.  
  498. CHECKPRINTER
  499.  
  500. This procedure checks if the specified parallel printer is ready and
  501. on-line. If so, it returns immediately with Ready% set to -1 (TRUE), if
  502. not, CHECKPRINTER displays the message 'PRINTER NOT READY' on the bottom
  503. row of the screen and waits for the operator to correct the problem and
  504. press a key.
  505.  
  506. If the user presses <Escape>, the procedure returns with Ready% set to
  507. zero (FALSE). Any other keystroke causes it to go back and test the
  508. printer again. CHECKPRINTER will not return until either the printer is
  509. ready for output, or the <Escape> key is pressed.
  510.  
  511. DECLARE SUB CheckPrinter (Prntr%, Ready%)
  512.  
  513. Prntr% is the number of the parallel printer to test (1 = LPT1: etc).
  514.  
  515. Example:    CheckPrinter 1, Ready%              ' Test LPT1:
  516.             IF NOT Ready% THEN
  517.                STOP
  518.             ELSE
  519.                LPRINT Stuff$
  520.             END IF 
  521.  
  522.  
  523. CIPHER
  524.  
  525. This routine requires that you supply two strings of characters. The first
  526. is the text to be encrypted, and the second is one or more keywords which
  527. are used to encipher the text. Thereafter, the text cannot be decrypted
  528. until you supply the same key string again.
  529.  
  530. DECLARE SUB Cipher (Text$, KeyWord$)
  531.  
  532. The encryption algorithm XORs (eXclusive ORs) the key string with string
  533. to be encrypted. This allows you to reverse the procedure and decrypt the
  534. text, simply by calling the routine a second time.
  535.  
  536. See the source code for DEMON.BAS, the ToolBox demonstration program, for
  537. an example using CIPHER.
  538.  
  539.  
  540. CLEAREND
  541.  
  542. Blank spaces of the display attribute specified are printed, starting at
  543. the current cursor position and continuing to the end of the line or,
  544. optionally, to the end of the screen.
  545.  
  546. DECLARE SUB ClearEnd (BYVAL Switch%, BYVAL Attr%)
  547.  
  548. Switch%   0 = clear to the end of the line.
  549.           1 = clear to the end of the screen.
  550.  
  551. Attr%     display attribute (1 - 255). If zero is specified then the
  552.           attribute of the character under the cursor is used.
  553.  
  554. Example:  ClearEnd 1, 0
  555.  
  556. Clears from the current cursor position to the bottom of the screen. The
  557. area cleared takes the background colour of the character under the
  558. cursor. The cursor, itself, is not updated.
  559.  
  560.  
  561. CONCEAL
  562.  
  563. Toggles the Hidden bit of the specified file's directory entry, making it
  564. visible or invisible to directory listings.
  565.  
  566. DECLARE SUB Conceal (BYVAL Switch%, FileSpec$)
  567.  
  568. If SWITCH% = 1 the file is hidden (regardless of whether it is currently
  569. visible or not), any other value makes the file visible. FileSpec$ is the
  570. name of the file to be hidden or unhidden. It can include a drive letter
  571. and directory path but must be an explicit pathname, wildcard characters
  572. are not allowed.
  573.  
  574. Note:   This routine was originally called HIDE in the QuickBASIC and
  575.         PDS Toolboxes. It has been changed because HIDE is a reserved
  576.         word in VisualBASIC DOS
  577.  
  578.  
  579. CPU
  580.  
  581. This function checks to see what type of microprocessor is installed in
  582. the computer in which the current program is running.
  583.  
  584. No calling parameters are required.
  585.  
  586. DECLARE FUNCTION Cpu% ()
  587.  
  588. The following processors can be identified by their return values :
  589.  
  590.  86 = Intel 8086          88 = Intel 8088         188 = Intel 80188        
  591. 186 = Intel 80186        286 = Intel 80286        386 = Intel 80386
  592. -86 = Intel 80C86        -88 = Intel 80C88         20 = NEC   V20
  593.  30 = NEC   V30
  594.  
  595. 486 = Intel 80486  included but not yet tested (lend us yours?).
  596.  
  597. This function is provided mainly for interest, although it can be used as
  598. an indication of how long a particular task will take to run. All of the
  599. Toolbox routines, in fact, are processor-independent and can be used on
  600. all types of IBM-PC, AT, PS/2 and compatible machines
  601.  
  602.  
  603. CURTAINS
  604.  
  605. This routine clears the display screen to the background colour specified
  606. by Attribute%. It differs from CLS in that the blanked-out area expands
  607. from a series of columns, giving the effect of a set of louvered blinds or
  608. curtains being closed. The Speed% parameter controls how quickly the
  609. routine runs, larger values making the curtains close more slowly.
  610.  
  611. DECLARE SUB Curtains (BYVAL Speed%, BYVAL Attribute%)
  612.  
  613. Try this example for a fancy effect:
  614.  
  615. FOR I% = 255 TO 0 STEP -16: Curtains 40, I%: NEXT
  616.  
  617. This procedure calls the DELAY routine (see below). This ensures that the
  618. speed value you specify will produce the same result on computers with any
  619. type of processor or clock speed.
  620.  
  621.  
  622. DATEINPUT
  623.  
  624. Accepts and verifies date input in a Reverse Video entry panel, all the
  625. usual editing keys are supported and entry is terminated by either a
  626. Carriage Return or one of several special function keys (see below).
  627.  
  628. DECLARE FUNCTION DateInput$ (Default$, Context%, Topic$, HotKey%)
  629.  
  630. Default$    =  default string which can be accepted by just pressing
  631.                the <Enter> key.
  632. Context%    =  set TRUE if context-sensitive help is available, in
  633.                which case ... 
  634. Topic$      =  name of the HELP Topic file to display whenever the
  635.                <F1> key is pressed. 
  636. HotKey%     =  If entry is terminated by anything other than the
  637.                <Enter> key, this variable will contain an explanatory
  638.                return code ..
  639.  
  640. Return Codes:   1  =  <Escape> abort entry returning a null string
  641.                 2  =  <F2>     repeat previous entry for this field
  642.                 3  =  <Up Arr> pressed, move to previous field 
  643.                 4  =  <Dn Arr> pressed, move to next field
  644.                 5  =  <Pg Up>  pressed, move to top of screen
  645.                 6  =  <Pg Dn>  pressed, move to end of screen
  646.  
  647. Editing Keys:   <L.Arrow>   =  Move cursor one character to the left
  648.                 <R.Arrow>   =  Move cursor one character to the right
  649.                 <Home>      =  Move cursor to first character of field
  650.                 <End>       =  Move cursor to last character of field
  651.                 <Ctrl End>  =  Clear from current cursor position to
  652.                                the end of the entry field.
  653.                 <BackSpace> =  Replace character under cursor with a
  654.                                blank space and move cursor one character
  655.                                to the left.
  656.                 <F1>        =  pop up on-line HELP screen.
  657.  
  658. DATEINPUT is designed to be used as part of a full-screen data-entry
  659. system. Your program can examine the return code to determine whether
  660. the operator wishes to terminate entry or move forwards or backwards
  661. between entry fields.
  662.  
  663. See also the REVINPUT function for a similar, more general-purpose,
  664. data-entry routine.
  665.  
  666.  
  667. DAYNUMBER
  668.  
  669. Convert a date in the form DD/MM/YYYY to a long integer. The values
  670. returned are valid with dates in the range 1/3/1900 - 31/12/2099.
  671.  
  672. DECLARE FUNCTION DayNumber& (BYVAL Dy%, BYVAL Mnth%, BYVAL Yr%)
  673.  
  674. See the INTERVAL function (below) for a method of calculating the number
  675. of days between two Julian dates.
  676.  
  677.  
  678. DAYSBETWEEN
  679.  
  680. Calculates the number of days between two dates, supplied as strings in
  681. the format DD/MM/YYYY. The function will provide accurate results when
  682. supplied with dates between 01/01/1901 and 31/12/2099.
  683.  
  684. DECLARE FUNCTION DaysBetween& (Date1$, Date2$)
  685.  
  686. See the INTERVAL function for a method of calculating the number of
  687. days between two Julian dates.
  688.  
  689.  
  690. DECBIN
  691.  
  692. Translates a decimal number to an equivalent string of binary digits.
  693.  
  694. DECLARE FUNCTION DecBin$ (Decimal&)
  695.  
  696.  
  697. DELAY
  698.  
  699. This procedure is like the QuickBASIC SLEEP statement, except that it
  700. allows you to specify an interval in milliseconds instead of just whole
  701. seconds. The delay will be exactly the same on a 4.77 MHz original PC as
  702. it would be on the latest 33-MHz 80486 machine.
  703.  
  704. DECLARE SUB Delay (BYVAL MilliSeconds%)
  705.  
  706. See the PAUSE routine (below) for a similar procedure which allows you to
  707. specify a delay in PC clock ticks.
  708.  
  709.  
  710. DISABLEPRTSC
  711.  
  712. This routine simply sets the Print Screen Busy flag at low-memory address
  713. 0040:0100 (Hex) so that any requests for the screen to be printed are
  714. ignored. Use this to prevent a careless operator from hanging-up the
  715. program by pressing <Prt Scrn> when the printer is off-line.
  716.  
  717. No calling parameters are required.
  718.  
  719. DECLARE SUB DisablePrtSc ()
  720.  
  721. Don't forget to use ENABLEPRTSC (see below) to re-enable this key
  722. otherwise it will remain disabled even after your program ends.
  723.  
  724.  
  725. DISKREADY
  726.  
  727. Tests if there is readable media in the floppy diskette drive specified. 
  728.  
  729. DRIVE% is the number of the diskette drive to be tested and is either
  730. zero (drive A:) or 1 (drive B:).
  731.  
  732. DECLARE FUNCTION DiskReady% (BYVAL Drive%)
  733.  
  734. This function returns a non-zero value if a readable diskette is in the
  735. drive, and zero (logical FALSE) if unable to read from the drive.
  736.  
  737. If the floppy disk in the drive specified is ready then the number that
  738. is returned is the Media Descriptor Byte, a value which indicates the
  739. type of diskette mounted, where:
  740.  
  741.       240   F0h  =  3.5"  2-sided, 18 sector
  742.       249   F9h  =  3.5"  2-sided, 9 sector or
  743.                     5.25" 2-sided, 15 sector
  744.       252   FCh  =  5.25" 1-sided, 9 sector
  745.       253   FDh  =  5.25" 2-sided, 9 sector
  746.       254   FEh  =  5.25" 1-sided, 8 sector
  747.       255   FFh  =  5.25" 2-sided, 8 sector             
  748.  
  749. DISKREADY only tests if the drive can be read from. It will not detect
  750. if the diskette in the drive is write-protected.
  751.  
  752.  
  753. DISPLAYMODE
  754.  
  755. Reads the current video display mode using the IBM ROM-BIOS numbering
  756. system.
  757.  
  758. DECLARE FUNCTION DisplayMode% ()
  759.  
  760. No calling parameters are required. Depending on the type of display
  761. adaptor installed, the function may return one of the following values:
  762.  
  763. Mode    Resolution      Mode     Colours    Remarks
  764. ─────────────────────────────────────────────────────────────────────
  765.   0     40 x 25         text        16      No colour burst
  766.   1     40 x 25         text        16      
  767.   2     80 x 25         text        16      No colour burst
  768.   3     80 x 25         text        16
  769.   4     320 x 200       graphics     4
  770.   5     320 x 200       graphics     4      No colour burst
  771.   6     640 x 200       graphics     2
  772.   7     80 x 25         text         2      Monochrome display only  
  773.   8     160 x 200       graphics    16      PCjr & Tandy 1000 only  
  774.   9     320 x 200       graphics    16      PCjr & Tandy 1000 only
  775.  10     640 x 200       graphics     4      PCjr & Tandy 1000 only
  776.  13     320 x 200       graphics    16      EGA & VGA
  777.  14     640 x 200       graphics    16      EGA & VGA
  778.  15     640 x 350       graphics     2      Monochrome EGA & VGA
  779.  16     640 x 350       graphics    16      EGA & VGA
  780.  17     640 x 480       graphics     2      VGA only
  781.  18     640 x 480       graphics    16      VGA only
  782.  19     320 x 200       graphics   256      VGA & MCGA      
  783. ─────────────────────────────────────────────────────────────────────
  784.  
  785. The SCREENMODE function (see below) can be used to return the equivalent
  786. QuickBASIC SCREEN number.
  787.  
  788.  
  789. DISPLAYPAGE
  790.  
  791. All video cards except the Monochrome Display Adaptor (MDA) are capable of
  792. switching between two or more pages of display memory. This function
  793. returns the number of the active video page, use the QuickBASIC SCREEN
  794. statement to select the page you require.
  795.  
  796. No calling parameters are required.
  797.  
  798. DECLARE FUNCTION DisplayPage% ()
  799.  
  800. The page number returned can be a value between 0 and 7, depending upon
  801. the current video mode and the amount of display memory installed.
  802.  
  803. Note:       all Toolbox routines which write directly to the screen will
  804.             automatically detect and send their output to the currently
  805.             active display page.
  806.  
  807.  
  808. DOSBOX
  809.  
  810. Restricts output directed to the console device to within the limits of
  811. the rectangular screen area you specify. Also allows you to specify the
  812. colour or display attribute of such output. When used in conjunction
  813. with the QuickBASIC SHELL command, this effectively lets you run DOS
  814. commands and programs in a window.
  815.  
  816. DECLARE SUB DOSBox (BYVAL Switch%, BYVAL Y1%, BYVAL X1%, BYVAL Y2%,_
  817.                     BYVAL X2%, BYVAL Attr%)
  818.  
  819. Arguments:  Switch%     1 = turn on output redirection  
  820.                         0 = turn off output redirection
  821.  
  822.             Y1%         Top-left row of screen rectangle
  823.  
  824.             X1%         Top-left column of screen rectangle
  825.             
  826.             Y2%         Bottom-right row of screen rectangle
  827.             
  828.             X2%         Bottom-right column of screen rectangle
  829.             
  830.             Attr%       Display attribute given to output.
  831.             
  832. This routine takes over the DOS internal 'FAST PUTCHAR' routine at
  833. Interrupt INT 29H which is called whenever DOS writes a character to
  834. the standard output device (the screen). You must remember to turn
  835. off any redirection, before your program ends, or the computer which
  836. it is running on will crash.
  837.  
  838. DOSBOX will only work properly with SHELLed programs which send screen
  839. output to standard output. All DOS internal and external commands do
  840. this as standard. Programs which write direct to video memory, however,
  841. and those which switch the display to graphics mode will behave
  842. unpredictablly when run from a DOSBOX SHELL.
  843.  
  844. For an example of how to use DOSBOX in action, see the source code for
  845. the SHELL to DOS option in the Exit menu of DEMON.BAS, the Toolbox
  846. demonstration program.
  847.  
  848.  
  849. DOSVERSION
  850.  
  851. Gets the current Operating System (DOS) version. The version is returned
  852. as a string in the form "3.20" (for DOS 3.2).
  853.  
  854. No calling parameters are required.
  855.  
  856. DECLARE FUNCTION DosVersion$ ()
  857.  
  858. The correct version will be returned, even under DOS 5.0 with SETVER
  859. set to report otherwise.
  860.  
  861.  
  862. DWPRINT
  863.  
  864. Sends the text supplied, to the printer, as a string of double-width
  865. characters. Output begins at the current print position and can,
  866. optionally, append a carriage-return/linefeed to take the print head to
  867. the beginning of a new line when finished.
  868.  
  869. DECLARE SUB DwPrint (BYVAL Prntr%, Buffer$, BYVAL NewLine%)
  870.  
  871. Arguments:  Prntr%      the parallel port output is to be sent to
  872.                         (1 = LPT1:, 2 = LPT2:, etc.).
  873.             Buffer$     the string of text to be printed.
  874.             NewLine%    set this to a non-zero value if you want 
  875.                         to move to a new line after printing.
  876.  
  877. The routine restores the previous print style or font before it returns
  878. and does not effect subsequent output to the printer, using the QuickBASIC
  879. LPRINT or PRINT # statements.
  880.  
  881. Note:       The version of this routine stored in the Toolbox
  882.             library is for EPSON compatible printers. If you have
  883.             an IBM graphics printer or ProPrinter, then you should
  884.             rebuild your libraries, using either the PRINTIBM.OBJ
  885.             or PRINTPRO.OBJ object module in place of PRINTEPS.OBJ.
  886.  
  887.  
  888. EMPRINT
  889.  
  890. Sends the text supplied, to the printer, as a string of emphasised
  891. characters. Output begins at the current print position and can,
  892. optionally, append a carriage-return/linefeed to take the print head to
  893. the beginning of a new line when finished.
  894.  
  895. DECLARE SUB EmPrint (BYVAL Prntr%, Buffer$, BYVAL NewLine%)
  896.  
  897. Arguments:  Prntr%      the parallel port output is to be sent to
  898.                         (1 = LPT1:, 2 = LPT2:, etc.).
  899.             Buffer$     the string of text to be printed.
  900.             NewLine%    set this to a non-zero value if you want 
  901.                         to move to a new line after printing.
  902.  
  903. The routine restores the previous print style or font before it returns
  904. and does not effect subsequent output to the printer, using the QuickBASIC
  905. LPRINT or PRINT # statements.
  906.  
  907. Note:       The version of this routine stored in the Toolbox
  908.             library is for EPSON compatible printers. If you have
  909.             an IBM graphics printer or ProPrinter, then you should
  910.             rebuild your libraries, using either the PRINTIBM.OBJ
  911.             or PRINTPRO.OBJ object module in place of PRINTEPS.OBJ.
  912.  
  913.  
  914. EMSERROR
  915.  
  916. Returns the code number of the last error which occurred during a
  917. call to the Expanded Memory Manager. If zero is returned, then no
  918. errors have occurred.
  919.  
  920. No calling parameters are required.
  921.  
  922. DECLARE FUNCTION EmsError% ()
  923.  
  924. Here is a list of possible error codes and their meanings:
  925.  
  926. 128  Internal error in EMM software     146  Source and target overlap
  927. 129  Malfunction in EMS hardware        147  Illegal region length
  928. 130  Memory manager busy                148  Region overlap
  929. 131  Invalid handle                     149  Offset outside logical page
  930. 132  Function not defined               150  Region length > 1MB
  931. 133  No more handles available          151  Cannot exchange overlap
  932. 134  Error in mapping context           152  Memory types undefined
  933. 135  Not enough pages exist             153  Not used
  934. 136  Not enough pages available         154  ARS not supported
  935. 137  Cannot allocate zero pages         155  ARS currently allocated
  936. 138  Page not allocated to handle       156  ARS not zero
  937. 139  Illegal physical page number       157  ARS not allocated
  938. 140  Save state area full               158  DMA channels not supported
  939. 141  Save of mapping context failed     159  Illegal DMA channel
  940. 142  Restore of mapping context failed  160  No handle for this name
  941. 143  Subfunction parameter not defined  161  Name already exists
  942. 144  Attribute type not defined         162  Memory address wrap
  943. 145  Feature not supported              163  Invalid pointer
  944.  
  945. 250  EMM not installed*                 251  LIM 4.0 required*
  946.  
  947. *    Toolbox error codes.
  948.  
  949. The descriptions are, of necessity, abbreviated. For more information 
  950. consult your EMS hardware manual or see:
  951.  
  952. Advanced MS-DOS Programming     by David Duncan     Microsoft Press
  953.  
  954.  
  955. EMSFRAME
  956.  
  957. Returns the segment address of the EMS page frame.
  958.  
  959. No calling parameters are required.
  960.  
  961. DECLARE FUNCTION EmsFrame% ()
  962.  
  963. The Page Frame is the area of conventional memory into which logical
  964. expanded memory pages are mapped. Under LIM 3.2 it is a contiguous
  965. block of 64RAM, divided into four 16K physical pages, located some-
  966. where between segments A000 and F000 Hex, but LIM 4.0 allows you to
  967. reserve additional 16K pages, wherever available memory exists. In
  968. either system you can rely on 4 consecutive 16K pages and this
  969. function returns a pointer to the first of them.
  970.  
  971.  
  972. EMSGET
  973.  
  974. Copies up to 64KB of data from expanded memory, starting at the
  975. logical page supplied, to an address in conventional memory.
  976.  
  977. DECLARE SUB EmsGet (BYVAL Segment%, BYVAL Offset%, BYVAL Length%,_
  978.                     BYVAL Page%, BYVAL Handle%, Done%)
  979.  
  980. Arguments:  Segment%  = segment address of target block to which
  981.                         data should be copied.
  982.             Offset%   = offset address, within target segment, to
  983.                         which data should be copied.
  984.             Length%   = length, in bytes (up to 64KB), of data to
  985.                         be copied. 
  986.             Page%     = logical EMS page holding the beginning of
  987.                         the data. If the block of data is bigger
  988.                         than 16KB, then copying will continue from
  989.                         subsequent pages until all the data has 
  990.                         been moved.
  991.             Handle%   = the EMS handle to which the page(s) have
  992.                         been allocated. This should be obtained by
  993.                         a previous call to the EMSRESERVE procedure
  994.                         (see below).
  995.             Done%     = a flag to hold the result of the operation.
  996.                         If the data was copied successfully, it is
  997.                         set to -1 (logical TRUE) on return. If zero
  998.                         (logical FALSE) is returned, the data was
  999.                         not copied successfully. In this case, you
  1000.                         should make a call to the EMSERROR function
  1001.                         to find out why.
  1002.  
  1003. If the target structure, to which the data is to be copied, is an
  1004. array, you should specify its address by supplying the VARSEG and
  1005. VARPTR of the first element. Be sure, however, that you do not copy
  1006. a block of data bigger than the array size, otherwise you may 
  1007. overwrite other variables, probably with disastrous results. 
  1008.  
  1009. See the EMSPUT procedure (below) for a means of copying data into
  1010. logical expanded memory pages.
  1011.  
  1012.  
  1013. EMSMAP
  1014.  
  1015. Map a logical expanded memory page to a physical page in the EMS
  1016. Page Frame, making it accessible to your program.
  1017.  
  1018. DECLARE SUB EmsMap (BYVAL Handle%, Physical%, Logical%)
  1019.  
  1020. Arguments:  Handle%   = the EMS handle to which the logical page has
  1021.                         been allocated. This will have been obtained
  1022.                         by a previous call to the EMSRESERVE routine
  1023.                         (see below).
  1024.             Physical% = the number of the physical page to map
  1025.                         (in the range 1 to 4).
  1026.             Logical%  = the number of the logical page to be mapped
  1027.                         (in the range from 1 to the number of pages
  1028.                         allocated to Handle%).
  1029.  
  1030. For most applications, the EMSGET and EMSPUT procedures will be more
  1031. useful, since they perform all the necessary mapping for you while
  1032. moving data to and from expanded memory. If, however, you need to
  1033. manipulate small quantities of data in expanded memory, use this
  1034. routine to switch the relevant page into conventional memory, and
  1035. the FARPEEK and FARPOKE utilities (see below) to examine or change
  1036. the data itself.
  1037.  
  1038.  
  1039. EMSOWNED
  1040.  
  1041. Returns the number of logical pages of EMS memory that have been
  1042. allocated to the handle specified.
  1043.  
  1044. DECLARE FUNCTION EmsOwned% (BYVAL Handle%)
  1045.  
  1046.  
  1047. EMSPAGES
  1048.  
  1049. Returns either the total number of EMS pages in the system, or the
  1050. total number of free (unallocated) pages.
  1051.  
  1052. DECLARE FUNCTION EmsPages% (BYVAL Switch%)
  1053.  
  1054. Argument:   Switch% = 1  return number of unallocated pages.
  1055.                       0  return total number of pages in system.
  1056.  
  1057.  
  1058. EMSPRESENT
  1059.  
  1060. Tests whether the Expanded Memory System driver has been installed
  1061.  
  1062. No calling parameters are required.
  1063.  
  1064. DECLARE FUNCTION EmsPresent% ()
  1065.  
  1066. Returns:    -1  (logical TRUE) if EMS driver is installed.
  1067.              0  (logical FALSE) if EMS driver is not installed.
  1068.  
  1069. Note:       This function just checks that the EMS driver is in
  1070.             memory and that the EMS interrupt vector is directed
  1071.             to it, it does not test if the driver is active. Use
  1072.             the EMSVERSION function (see below) to test this. If
  1073.             the driver responds to that function, it can be safely
  1074.             assumed to be active.
  1075.  
  1076.  
  1077. EMSPUT
  1078.  
  1079. Copies up to 64KB of data to expanded memory, starting at the
  1080. logical page supplied, from an address in conventional memory.
  1081.  
  1082. DECLARE SUB EmsPut (BYVAL Segment%, BYVAL Offset%, BYVAL Length%,_
  1083.                     BYVAL Page%, BYVAL Handle%, Done%)
  1084.  
  1085. Arguments:  Segment%  = segment address of source block from which
  1086.                         data is to be copied.
  1087.             Offset%   = offset address, within target segment, from
  1088.                         which data is to be be copied.
  1089.             Length%   = length, in bytes (up to 64KB), of data to
  1090.                         be copied to expanded memory. 
  1091.             Page%     = logical EMS page to hold the beginning of
  1092.                         the data. If the block of data is bigger
  1093.                         than 16KB, then copying will continue onto
  1094.                         subsequent pages until all the data has 
  1095.                         been moved.
  1096.             Handle%   = the EMS handle to which the page(s) have
  1097.                         been allocated. This should be obtained by
  1098.                         a previous call to the EMSRESERVE procedure
  1099.                         (see below).
  1100.             Done%     = a flag to hold the result of the operation.
  1101.                         If the data is copied successfully, it will
  1102.                         be set to -1 (logical TRUE) on return. If
  1103.                         zero (logical FALSE) is returned, the data
  1104.                         was not copied successfully. In this case,
  1105.                         you should make a call to the EMSERROR
  1106.                         function to find out why.
  1107.  
  1108. If the source structure, from which the data is to be copied, is an
  1109. array, you should specify its address by supplying the VARSEG and
  1110. VARPTR of the first element. You can also copy data from absolute
  1111. addresses in memory to EMS, to copy the contents of the text screen,
  1112. for example, to EMS logical page 2, use the command:
  1113.  
  1114.     EmsPut &HB800, 0, 4000, 3, Handle%, Done%
  1115.  
  1116. This assumes that your computer has a colour monitor. If you have a
  1117. monochrome display, substitute &HB000 for the segment address.
  1118.  
  1119. See the EMSGET procedure (above) for a means of retrieving data from
  1120. extended memory.
  1121.  
  1122.  
  1123. EMSRELEASE
  1124.  
  1125. Free-up all the pages previously allocated to this handle, and make
  1126. them available to other processes.
  1127.  
  1128. DECLARE SUB EmsRelease (BYVAL Handle%)
  1129.  
  1130. You should release all the EMS pages which have been allocated to
  1131. handles owned by your program, before the program terminates. If
  1132. this is not done, these pages will not be available to subsequent
  1133. programs which may start up and will remain locked until the system
  1134. is rebooted.
  1135.  
  1136.  
  1137. EMSREQUEST
  1138.  
  1139. Asks for one or more logical pages of expanded memory to be made
  1140. available to your program.
  1141.  
  1142. DECLARE SUB EmsRequest (BYVAL Pages%, Handle%)
  1143.  
  1144. Arguments:  Pages%  = number of EMS pages to reserve.
  1145.  
  1146.             Handle% = if successful, this variable will hold the
  1147.                       number of the EMS handle which controls the
  1148.                       allocated pages. If unsuccessful, Handle%
  1149.                       will be set to zero on return, in which case
  1150.                       you should call the EMSERROR function (above)
  1151.                       to see what went wrong.
  1152.  
  1153. You must use this handle in all subsequent calls to the Expanded
  1154. Memory Manager which refer to these particular pages.
  1155.  
  1156. Before calling this procedure, it is a good idea to make a call to
  1157. the EMSPAGES function (see above) to see how many pages are free.
  1158.  
  1159.  
  1160. EMSRESIZE
  1161.  
  1162. Changes the number of pages allocated to an EMS handle.
  1163.  
  1164. DECLARE SUB EmsReSize (BYVAL Handle%, Pages%)
  1165.  
  1166. Arguments:  Handle% = a valid EMS handle to which logical expanded
  1167.                       memory pages have already been allocated.
  1168.  
  1169.             Pages%  = the new number of pages to be allocated to
  1170.                       this handle.
  1171.  
  1172. On return, Pages% will hold the actual number of pages that are
  1173. now allocated to the handle. If this is different from the number
  1174. of pages requested, then an error has occurred and you should call
  1175. the EMSERROR function (see above) to check what happened.
  1176.  
  1177. You can request a number of pages less than or greater than the
  1178. number previously allocated to the handle.
  1179.  
  1180. Note:       This facility is only available with LIM 4.0 EMS and
  1181.             above.
  1182.  
  1183.  
  1184. EMSVERSION
  1185.  
  1186. Returns the LIM version number of the Expanded Memory Manager.
  1187.  
  1188. No calling parameters are required.
  1189.  
  1190. DECLARE FUNCTION EmsVersion% ()
  1191.  
  1192. The number returned is a decimal integer where 32 represents LIM 3.2
  1193. and 40 represents LIM 4.0. If zero is returned, then an error has
  1194. occurred and you should call the EMSERROR function (see above) to
  1195. find out what happened. Use the EMSPRESENT function (also above) to
  1196. test that the EMM driver has, in fact, been installed.
  1197.  
  1198.  
  1199. ENABLEPRTSC
  1200.  
  1201. This routine clears the Busy flag at low-memory address 0040:0100 (Hex) so
  1202. that print-screen requests can be executed. Use it to cancel the effect of
  1203. the DISABLEPRTSC procedure (above).
  1204.  
  1205. No calling parameters are required.
  1206.  
  1207. DECLARE SUB EnablePrtSc ()
  1208.  
  1209.  
  1210. ENPRINT
  1211.  
  1212. Sends the text supplied, to the printer, as a string of enhanced
  1213. characters. Output begins at the current print position and can,
  1214. optionally, append a carriage-return/linefeed to take the print head to
  1215. the beginning of a new line when finished.
  1216.  
  1217. DECLARE SUB EnPrint (BYVAL Prntr%, Buffer$, BYVAL NewLine%)
  1218.  
  1219. Arguments:  Prntr%      the parallel port output is to be sent to
  1220.                         (1 = LPT1:, 2 = LPT2:, etc.).
  1221.             Buffer$     the string of text to be printed.
  1222.             NewLine%    set this to a non-zero value if you want 
  1223.                         to move to a new line after printing.
  1224.  
  1225. The routine restores the previous print style or font before it returns
  1226. and does not effect subsequent output to the printer, using the QuickBASIC
  1227. LPRINT or PRINT # statements.
  1228.  
  1229. Note:       The version of this routine stored in the Toolbox
  1230.             library is for EPSON compatible printers. If you have
  1231.             an IBM graphics printer or ProPrinter, then you should
  1232.             rebuild your libraries, using either the PRINTIBM.OBJ
  1233.             or PRINTPRO.OBJ object module in place of PRINTEPS.OBJ.
  1234.  
  1235.  
  1236. EXPLODE
  1237.  
  1238. Clear a screen rectangle explosively. This as an alternative to the
  1239. SCROLL routine listed below.
  1240.  
  1241. DECLARE SUB Explode (BYVAL Y1%, BYVAL X1%, BYVAL Y2%, BYVAL X2%,_
  1242.                      BYVAL Attr%, BYVAL Speed%)
  1243.  
  1244. Arguments:  Y1%         =  Upper-left row of rectangle to be cleared
  1245.             X1%         =  Upper-left column of rectangle
  1246.             Y2%         =  Lower-right row of rectangle
  1247.             X2%         =  Lower-right column of rectangle
  1248.             Attr%       =  Display attribute or colour that rectangle
  1249.                            should be cleared to 
  1250.             Speed%      =  Speed (in milliseconds) of explosion.
  1251.  
  1252. The panel is cleared, starting at the centre point, and progressively
  1253. moving outwards until the defined borders are reached. This gives the
  1254. impression of the clear area exploding onto the screen.
  1255.  
  1256. This routine is called, internally, by the POPUP window function (see
  1257. below) whenever Zoom is specified.
  1258.  
  1259.  
  1260. FARPEEK
  1261.  
  1262. Reads a byte of data from anywhere in conventional memory.
  1263.  
  1264. DECLARE FUNCTION FarPeek% (BYVAL Segment&, BYVAL Offset&)
  1265.  
  1266. Arguments:  Segment&  = address of memory segment containing the byte
  1267.                         to be read.
  1268.             Offset&   = offset address, within the segment of the 
  1269.                         byte to be read.
  1270.  
  1271. Returns:    The contents of the byte specified as an integer value
  1272.             in the range 0 to 255.
  1273.  
  1274. Note:       parameters are passed as LONG integers to save you the
  1275.             hassle of having to convert argument values over 32767
  1276.             to negative signed integers. Do not use values greater
  1277.             than 65535, however, or the most significant word will
  1278.             be ignored and the address converted to Modulus 65536.
  1279.  
  1280. Using QuickBASIC's PEEK function to examine data which lies outside
  1281. of DGROUP is a pain. You also have to use DEF SEG to set the segment
  1282. required and then to reset it afterwards. This function allows you to
  1283. read bytes, directly, from anywhere in the 1 megabyte of addressable
  1284. RAM space your computer contains.
  1285.  
  1286. The FARPOKE procedure (below) complements FARPEEK by allowing you to
  1287. write a byte of data anywhere in the 1MB addressable PC workspace.
  1288.  
  1289. See also PEEKWORD and POKEWORD which allow you to read from and write
  1290. to memory, two bytes at a time.
  1291.  
  1292. Note:       If you have an Intel 286, 386 or 486-based computer with
  1293.             the Microsoft HIMEM.SYS driver loaded, you can even use
  1294.             FARPEEK to read from the first 64KB of Extended Memory.
  1295.             Setting the segment to &HFFFF and an offset in the range
  1296.             &H10 to &HFFFF allows you access up to 65520 bytes of
  1297.             memory ABOVE the normal 1MB limit.
  1298.  
  1299.  
  1300. FARPOKE
  1301.  
  1302. Writes a byte of data to anywhere in conventional memory.
  1303.  
  1304. DECLARE SUB FarPoke (BYVAL Segment&, BYVAL Offset&, BYVAL Byte%)
  1305.  
  1306. Arguments:  Segment&  = address of memory segment containing the byte
  1307.                         to be written to
  1308.             Offset&   = offset address, within the segment of the 
  1309.                         byte to be written.
  1310.             Byte%     = the value (0 to 255) to be written to the
  1311.                         specified byte.
  1312.  
  1313. Note:       addresses are passed as LONG integers to save you the
  1314.             hassle of having to convert argument values over 32767
  1315.             to negative signed integers. Do not use values greater
  1316.             than 65535, however, or the most significant word will
  1317.             be ignored and the address converted to Modulus 65536.
  1318.  
  1319. Using QuickBASIC's POKE function to write to memory which is outside
  1320. of DGROUP is a pain. You also have to use DEF SEG to set the segment
  1321. you want and then to set it back again afterwards. This function lets
  1322. you write bytes, directly, anywhere in the 1 megabyte of addressable
  1323. RAM space your computer contains.
  1324.  
  1325. The FARPEEK procedure (above) complements FARPOKE by allowing you to
  1326. read a byte of data from anywhere in the 1MB of addressable memory.
  1327.  
  1328. See also PEEKWORD and POKEWORD which allow you to read from and write
  1329. to memory, two bytes at a time.
  1330.  
  1331.  
  1332. FASTPRINT
  1333.  
  1334. This procedure can be used to display a string of text directly to video
  1335. memory. It is much  faster than the normal DOS services and does not
  1336. update the cursor.
  1337.  
  1338. DECLARE SUB FastPrint (BYVAL Row%, BYVAL Col%, Message$, BYVAL Attr%)
  1339.  
  1340. Row%        is the row where printing is to start.
  1341. Col%        is the column where printing is to start.
  1342. Message$    is the string of text to be printed.
  1343. Attr%       is the video attribute given to the text.
  1344.  
  1345. Row% and Col% follow the QuickBASIC convention of numbering screen rows
  1346. and columns with Row = 1, Column = 1 being at the top-left corner of the
  1347. display. The maximum value for Row% depends on the capabilities of the
  1348. video adaptor installed and is determined by the last WIDTH statement.
  1349. Normally it is 25 but may extend to 43 (EGA) or even 50 rows (VGA).
  1350. Maximum columns may be either 40 or 80 (the default).
  1351.  
  1352. If multiple screen pages are being used, FASTPRINT will correctly identify
  1353. the active one and output to the proper video address.
  1354.  
  1355. Note:       if an attribute of -1 is specified, the output string takes
  1356.             the colour or attribute already set into that portion of the
  1357.             screen where the string is printed.
  1358.             
  1359. Thanks to John Turnbull of Macclesfield for this suggestion.
  1360.             
  1361.  
  1362. FILEDATE
  1363.  
  1364. Gets or sets the date and time of the specified file as is displayed in
  1365. directory listings.
  1366.  
  1367. DECLARE SUB FileDate (BYVAL Switch%, DateTime$, FileSpec$)
  1368.  
  1369. Switch%     if set to a value of 1, changes the date and time of the file
  1370.             to the parameters specified in DateTime$. Any other value
  1371.             returns the date and time that the file was last written to
  1372.             in DateTime$
  1373.  
  1374. DateTime$   A string of at least 17 characters in length. If setting the
  1375.             date and time of a file, this must be written in a standard
  1376.             UK date/time format, ie:
  1377.  
  1378.             "DD/MM/YY HH:MM:SS"
  1379.  
  1380.             If you are reading the date and time, it is not necessary to
  1381.             pre-format the string, as the function will do it for you. The
  1382.             string must be of sufficient length to hold the returned date
  1383.             and time, however, or the procedure will fail.
  1384.  
  1385. FileSpec$   A string holding the pathname of the file to be examined or
  1386.             changed. It can include the drive letter and directory path
  1387.             were appropriate, but must be an explicit pathname. Wildcard
  1388.             characters are not allowed. Maximum length is 64 characters.
  1389.  
  1390. The procedure will fail if the file does not exist or is not on the path
  1391. specified. Also, since the file is actually opened by the procedure, there
  1392. must be at least one free DOS file handle available when you call it.
  1393.  
  1394. You cannot change the date and time of a file which has been flagged as
  1395. readonly or, on a network, is owned by another program.
  1396.  
  1397.  
  1398. FILESIZE
  1399.  
  1400. This function will return the size of the file specified in bytes, or, if
  1401. more than one match is found, the total size of all such files. If a size
  1402. of zero is returned, no matching file exists (at least not in the
  1403. directory specified).
  1404.  
  1405. DECLARE FUNCTION FileSize& (FileSpec$)
  1406.  
  1407. The filename can include a directory path and may be ambiguous, using the
  1408. wildcard characters '*' and '?'.
  1409.  
  1410. Note:   In previous versions of the Toolbox this function was called
  1411.         SIZEOF. In MASM 6, however, SIZEOF is now a reserved word so the
  1412.         name has had to be changed.
  1413.  
  1414.  
  1415. FINDFILE
  1416.  
  1417. This function can be used to locate a particular file in any drive or
  1418. directory of the current system. Supply it with a pathname or an ambiguous
  1419. filespec and it will display a list of all matching files from which the
  1420. user can select the one required by highlighting it with the cursor arrow
  1421. keys. The function returns the full pathname of the file selected or a
  1422. null string if <ESC> was pressed.
  1423.  
  1424. DECLARE FUNCTION FindFile$ (FileSpec$, Attr%, Mouse%)
  1425.  
  1426. FileSpec$   =  Pathname of file to be located. It can include a drive
  1427.                letter and the filename may be ambiguous if you use the
  1428.                wildcard characters '*' or '?'.
  1429.  
  1430. Attr%       =  The display attribute for the file selection box if more
  1431.                than one match is expected. If Attr% = 0 the function
  1432.                uses the default of inverse video with a 3-dimensional
  1433.                sculptured look.
  1434.  
  1435. Mouse%      =  set this to TRUE (non-zero) if mouse support is required.
  1436.  
  1437. On entry, FILESPEC$ should contain the name of the file to be located. If
  1438. the filespec is ambiguous, the program presents a directory listing, in a
  1439. popup window, of all files which match and allows the operator to select
  1440. the actual one required. If the pathname is explicit, FindFile just checks
  1441. if it actually exists. On return FILESPEC$, will contain the full pathname
  1442. of the selected file, or a null string if it was not located (or the
  1443. <Escape> key was pressed).
  1444.  
  1445.  
  1446. FLOPPYDRIVES
  1447.  
  1448. This function returns the number of installed diskette drives in the
  1449. current computer system.
  1450.  
  1451. DECLARE FUNCTION FloppyDrives% ()
  1452.  
  1453. No calling parameters are required.
  1454.  
  1455.  
  1456. FREESPACE
  1457.  
  1458. You must supply the drive number of the diskette or fixed-disk which you
  1459. want to test (1 = drive A:, 2 = drive B:, etc). Pass a value of zero to
  1460. test the currently-logged or default drive. The amount of free space is
  1461. returned in bytes.
  1462.  
  1463. DECLARE FUNCTION FreeSpace& (BYVAL DriveNo%)
  1464.  
  1465. Note:       The return value will not be reliable if the drive being
  1466.             tested has an extended DOS partition which contains more
  1467.             than 32MB of free space.
  1468.  
  1469.  
  1470. GAMESPORT
  1471.  
  1472. This function checks to see if the host computer is fitted with an adaptor
  1473. for joysticks or a games paddle.
  1474.  
  1475. No calling parameters are required.
  1476.  
  1477. DECLARE FUNCTION GamesPort% ()
  1478.  
  1479. Returns logical TRUE (-1) if a games adaptor is present or FALSE (0) if no
  1480. games adaptor is fitted.
  1481.  
  1482.  
  1483. GETFLAG
  1484.  
  1485. The MIXED-LANGUAGE Toolbox includes a pair of functions which give you
  1486. access to the INTRA-APPLICATION COMMUNICATION AREA (IAC), an area of
  1487. memory which has been reserved, by DOS, so that programs can communicate
  1488. with each other. The IAC is 16 bytes long and is located, in low RAM at
  1489. addresses 0000:04F0 - 04FF (Hex). Once set, an IAC flag retains it's value
  1490. until you reset it or the computer is rebooted.
  1491.  
  1492. This function returns the value of one of the IAC flag bytes (1 to 16).
  1493.  
  1494. DECLARE FUNCTION GetFlag% (Flag%)
  1495.  
  1496. You can set the current setting of a particular IAC flag byte with the
  1497. SETFLAG function.
  1498.  
  1499. Since QuickBASIC programs, compiled with the /O switch to run stand-alone,
  1500. cannot pass variables to chain modules, you can use this feature to
  1501. implement a limited form of parameter passing.
  1502.  
  1503.  
  1504. GRAPRINT
  1505.  
  1506. This routine simply serves as a function despatcher for the various
  1507. graphics text procedures, which can also be called directly. It is
  1508. intended to be called from programs which must run under a variety of
  1509. video adaptors, transferring control to the proper routine for the current
  1510. video mode. The calling program must supply appropriate parameters,
  1511. however.
  1512.  
  1513. DECLARE SUB GraPrint (BYVAL xLoc%, BYVAL yLoc%, Text$,_
  1514.                       BYVAL Attr%, BYVAL Scale%)
  1515.  
  1516. GRAPRINT provides a convenient way of displaying text in any of the EGA,
  1517. VGA and MCGA graphics modes (SCREENs 7-13) as well as the 320 x 200 pixel
  1518. 4-colour CGA mode (SCREEN 1) without having to bother about loading
  1519. external font files. It uses the standard character definition tables
  1520. built into your display adaptor, but allows you to scale them up to eight
  1521. times normal size and to specify any combination of foreground and
  1522. background colours supported by the current video mode.
  1523.  
  1524. XLOC%       The horizontal co-ordinate of the top left hand pixel
  1525.             from which the text will begin
  1526.  
  1527. YLOC%       The vertical co-ordinate of the top left hand pixel
  1528.             from which the text will begin
  1529.  
  1530. TEXT$       The string of text to be displayed (up to 63 characters).
  1531.  
  1532. ATTR%       The colour (or display attribute in monochrome modes) to
  1533.             be given to the text. This is calculated by the formula:
  1534.  
  1535.             Colour% = (Background% * 256) + Foreground%
  1536.  
  1537.             The GRATTRIB function (see below) will perform this
  1538.             calculation for you, automatically, using the foreground
  1539.             and background values you supply.
  1540.  
  1541.             Foreground and Background values are in the ranges used
  1542.             by the current video mode (eg. 0 - 15 for SCREEN 9). The
  1543.             actual colours displayed depend upon your current PALETTE
  1544.             settings.
  1545.  
  1546.             Note:   supplying a value of -1 for background prevents
  1547.                     background pixels from being changed at all. This
  1548.                     allows text to be blended more naturally into a
  1549.                     complex graphics display, it is not supported in
  1550.                     320 x 200 4-colour mode, however.
  1551.  
  1552. SCALE%      The character size of the text to be displayed. This ranges
  1553.             from 1 to 8, where 1 is standard 80-column text (40-column
  1554.             in SCREEN 7) and 8 multiplies the character size by eight
  1555.             on both the horizontal and vertical axes.
  1556.  
  1557. GRAPRINT can handle both byte-aligned and non byte-aligned characters. The
  1558. x, y co-ordinates you supply do not need to correspond to a row, column
  1559. character cell in SCREEN 0, the alphanumeric mode. The complete extended
  1560. ASCII character set is supported, including foreign symbols and box-
  1561. drawing characters (computers with CGA adaptors must have GRAFTBL loaded
  1562. to access characters above ASCII 127, however).
  1563.  
  1564. Since GRAPRINT does not support clipping, to ensure a clean display you
  1565. must ensure that the text to be output fits within the current screen
  1566. boundaries.
  1567.  
  1568. See also CGATEXT for displaying characters in SCREEN 1, MCGATEXT for
  1569. displaying characters in SCREEN 13 and VGATEXT for displaying text in
  1570. the EGA and VGA video modes (SCREENs 7-12).
  1571.  
  1572.  
  1573. GRATTRIB
  1574.  
  1575. Calculate display attribute for graphics modes, given the foreground
  1576. and background colours required.
  1577.  
  1578. DECLARE FUNCTION GrAttrib% (ForeGround%, BackGround%)
  1579.  
  1580. GRATTRIB calculates the attribute value which controls the foreground and
  1581. background colours of characters displayed using the GRAPRINT, CGATEXT,
  1582. MCGATEXT and VGATEXT procedures. It translates them using the formula:
  1583.  
  1584.     Attribute% = (BackGround% * 256) + ForeGround%
  1585.  
  1586. Make sure that you use foreground and background colour values appropriate
  1587. to the SCREEN mode currently in use.
  1588.  
  1589. The ATTRIBUTE function provides a similar service for use with text mode
  1590. screens
  1591.  
  1592.  
  1593. HANDLES
  1594.  
  1595. Returns the number of file handles available in the System File Table
  1596.  
  1597. DECLARE FUNCTION Handles% ()
  1598.  
  1599. The number returned by this function is equivalent to the value given
  1600. to the FILES = statement in your CONFIG.SYS script. Note that the first
  1601. five of these handles are reserved for DOS's internal use.
  1602.  
  1603.  
  1604. HELPMATE
  1605.  
  1606. This routine provides a context-sensitive on-line Help facility for your
  1607. QuickBASIC programs.
  1608.  
  1609. DECLARE SUB HelpMate (BYVAL Colour%, Title$, BYVAL Context%, Topic$)
  1610.  
  1611. Colour%   is the display attribute to be given to the Help window. If a
  1612.           value of zero is passed, HELPMATE uses default colours which
  1613.           are Black on Cyan for colour screens and inverse video for a
  1614.           monochrome display.
  1615.  
  1616. Title$    is an optional Title for the Help window. If one is supplied
  1617.           it must be no longer than 48 characters so that it can be
  1618.           easily centered in the top row of the window. If Title$ is a
  1619.           null string, HELPMATE uses its' own name as a default.  
  1620.  
  1621. Context%  is the context-sensitive flag. If set to 1, then the routine
  1622.           attempts to load the file specified by ...
  1623.  
  1624. Topic$    A legal DOS filename (up to 8 characters without extension),
  1625.           specifying the name of the Topic file to be displayed. 
  1626.           HelpMate automatically appends the extension '.HLP'.  
  1627.  
  1628. If Context% is not set, (or Topic$ is a null string), then the routine
  1629. displays a list of topics, from which you can make your own selection.
  1630.  
  1631. If Context% is set, HELPMATE will display the first page of the Topic file
  1632. specified, otherwise it begins by  overlaying the current screen with a
  1633. popup window in which is listed those HELP topics available.
  1634.  
  1635. The first topic in the list is highlighted and you can move the highlight
  1636. around the menu with the arrow keys Highlight the topic you want, then
  1637. press the <RETURN> key. The first page of that topic will be displayed in
  1638. the HELP window.
  1639.  
  1640. Page backwards and forwards through the file using the <PG UP> and <PG DN>
  1641. keys. If you page past the end of the file you will be returned to the
  1642. topic list, where you can either select another topic, or press <ESC> to
  1643. return to the QuickBASIC program. On return, the original screen and all
  1644. current variables are restored, intact, and program execution will
  1645. continue with the statement following the procedure call.
  1646.  
  1647. By default, the Toolbox Help system looks for its topic files in a sub-
  1648. directory called HELP, beneath the currently-logged directory. You can,
  1649. however, direct it to look elsewhere for files by setting a HELP variable
  1650. in the DOS environment table
  1651.  
  1652. e.g.  SET HELP=C:\BASIC\TOOLBOX\HELP
  1653.  
  1654. Alternatively, you can use the QuickBASIC ENVIRON statement within your
  1655. program, to point HELPMATE to the appropriate pathname. Remember, though,
  1656. that this method only remains in effect as long as the current program is
  1657. running and that there must be enough environment space available to hold
  1658. the HELP directory pathname.
  1659.  
  1660. A set of example Topic files, for use with the demonstration program,
  1661. DEMON.EXE is supplied with the Assembly-Language ToolBox. You can make
  1662. your own, using any Word Processor or Text Editor which can output plain
  1663. ASCII text (EDLIN will do). If you do so, bear in mind that the HelpMate
  1664. window's maximum page size is 16 rows of 55-column text. The maximum
  1665. number of pages in any one file is 256.
  1666.  
  1667.                              TIP
  1668.  
  1669. When displaying the list of available Topics, HelpMate searches the
  1670. current HELP directory for files with the extension .HLP. However, since
  1671. there is only room for 60 such filenames to be displayed in the menu
  1672. window, any files in excess of this number will be not be listed and are,
  1673. hence, inaccessible. You can, however, read any number of Context-
  1674. sensitive topic files since these are named explicitly in the call to
  1675. HelpMate which loads them. They need not, therefore, appear in the Topic
  1676. list.
  1677.  
  1678. If your application needs to provide a large number of Topic files, it is
  1679. a good idea to hide those which are context-sensitive from normal
  1680. directory searches (you can use the Toolbox Hide function to do this).
  1681. This will not prevent these files from being loaded when called, but it
  1682. does prevent them from appearing in the Topic list which gives you more
  1683. room for those general-purpose topic files which are selected by the user.
  1684.  
  1685. Note:       The \HELP directory on the ToolBox distribution disk
  1686.             contains a number of these hidden files for use by the
  1687.             demonstration program DEMON.EXE.
  1688.  
  1689.  
  1690. HIBYTE
  1691.  
  1692. Returns the value contained in the Most Significant Byte (MSB) of a
  1693. two-byte integer. This is effectively the same as dividing the
  1694. number by 256.
  1695.  
  1696. DECLARE FUNCTION HiByte% (BYVAL Number%)
  1697.  
  1698. See LOBYTE for a function which returns the Least Significant Byte
  1699. (LSB) of an integer.
  1700.  
  1701.  
  1702. HIWORD
  1703.  
  1704. Returns the value contained in the Most Signifant Word (MSW) of a
  1705. four-byte long integer. This is effectively the same as dividing the
  1706. number by 65536.
  1707.  
  1708. DECLARE FUNCTION HiWord% (BYVAL Number&)
  1709.  
  1710. See LOWORD for a function which returns the Least Significant Word
  1711. (LSW) of a long integer.
  1712.  
  1713.  
  1714. INFORM
  1715.  
  1716. Displays the message supplied in a dialogue box and waits for the user to
  1717. press the <ENTER> key before restoring the screen to its' previous state.
  1718.  
  1719. DECLARE SUB Inform (BYVAL Row%, Message$, BYVAL Attr%, BYVAL Mouse%)
  1720.  
  1721. ROW%        The top row of the dialogue box when it is displayed. The
  1722.             box is automatically centered within this row, which may be
  1723.             adjusted so that it remains within the screen boundaries.
  1724.  
  1725. MESSAGE$    A string of text comprising the message to be displayed. It
  1726.             must be no longer than 40 characters otherwise it will be
  1727.             truncated to fit inside the display panel.
  1728.  
  1729. ATTR%       The display attribute or colour to be given to the dialogue
  1730.             box. If an argument of zero is supplied, the box is displayed
  1731.             in cyan with a black foreground (colour monitors) or reverse
  1732.             video (monochrome monitors). On colour displays the message
  1733.             text always has a white foreground, no matter what attribute
  1734.             is specified.
  1735.  
  1736. MOUSE%      Should be set to TRUE (-1) or FALSE (0) to indicate if a
  1737.             mouse is available for use. If available, the operator can
  1738.             respond by clicking the left mouse button while the cursor is
  1739.             positioned on the radio button.     
  1740.  
  1741. This procedure is nearly identical to the MISTAKE routine (below) which is
  1742. designed for displaying error messages.
  1743.  
  1744.  
  1745. INT2E
  1746.  
  1747. Provides an interface to the MS-DOS kernel interrupt 2E (hex) service
  1748. which is sometimes called the 'Back Door to the Command Processor'.
  1749.  
  1750. DECLARE SUB Int2E (DosCmd$)
  1751.  
  1752. DosCmd$ can contain any legal MS-DOS command including the name of an
  1753. external program to be executed. 
  1754.  
  1755. INT2E is an alternative to the SHELL command already provided by
  1756. QuickBASIC. It has one advantage, however, in that many commands are
  1757. passed directly to the MS-DOS kernal instead of to a secondary copy
  1758. of the command processor. For example a SET command passed to INT2E
  1759. will set a string in the MS-DOS master environment instead of the
  1760. current program's local environment. Master environment variables
  1761. are preserved when the program terminates and are available to any
  1762. subsequent programs which may be started up.
  1763.  
  1764. If the command you pass is the name of an external command or if it
  1765. requires COMMAND.COM to be loaded then you must make sure that there
  1766. is enough memory available for it to be executed. You can free-up
  1767. memory by using QuickBASIC's SETMEM function with the appropriate
  1768. negative value.
  1769.  
  1770. Be aware that the INT 2Eh service is not documented or supported by
  1771. Microsoft and successful operation cannot be guaranteed. If the
  1772. procedure fails due to there being insufficient memory or for some 
  1773. other reason, no error message will be returned. For this reason,
  1774. the SHELL statement is usually to be preferred for accessing MS-DOS
  1775. functions, since this can be trapped for errors.
  1776.  
  1777. Note that INT2E will only work with genuine versions of Microsoft
  1778. MS-DOS or IBM PC-DOS. It will not work under DR-DOS, Norton NDOS or
  1779. versions of 4DOS prior to 4.0.
  1780.  
  1781.  
  1782. INTERVAL
  1783.  
  1784. Calculate the number of days between two dates supplied as long integer
  1785. Julian numbers. You can use the DAYNUMBER function (see above) to turn
  1786. dates in normal numeric format into Julian numbers and NUMBERDAY (below)
  1787. to convert them back again.
  1788.  
  1789. DECLARE FUNCTION Interval& (First&, Second&)
  1790.  
  1791. This function always returns a positive value, regardless of whether the
  1792. first argument is lower or greater than the second.
  1793.  
  1794.  
  1795. ISDIR
  1796.  
  1797. This routine tests to see if the supplied string is the name of a
  1798. directory. To do this a local error handler is established to trap any
  1799. run-time errors and an attempt is made to change to the directory
  1800. specified in TEST$. If an error occurs then ISDIR% is set to Boolean FALSE
  1801. (zero), otherwise TRUE (-1) is returned.
  1802.  
  1803. DECLARE FUNCTION IsDir% (Test$)
  1804.  
  1805. ISDIR is used by the FINDFILE function when searching for files on another
  1806. drive or directory.
  1807.  
  1808.  
  1809. ITPRINT
  1810.  
  1811. Sends the text supplied, to the printer, as a string of italic characters.
  1812. Output begins at the current print position and can, optionally, append a
  1813. carriage-return/linefeed to take the print head to the beginning of a new
  1814. line when finished.
  1815.  
  1816. DECLARE SUB ItPrint (BYVAL Prntr%, Buffer$, BYVAL NewLine%)
  1817.  
  1818. Arguments:  Prntr%      the parallel port output is to be sent to
  1819.                         (1 = LPT1:, 2 = LPT2:, etc.).
  1820.             Buffer$     the string of text to be printed.
  1821.             NewLine%    set this to a non-zero value if you want 
  1822.                         to move to a new line after printing.
  1823.  
  1824. The routine restores the previous print style or font before it returns
  1825. and does not effect subsequent output to the printer, using the QuickBASIC
  1826. LPRINT or PRINT # statements.
  1827.  
  1828. Note:       The version of this routine stored in the Toolbox
  1829.             library is for EPSON compatible printers. If you have
  1830.             an IBM graphics printer or ProPrinter, then you should
  1831.             rebuild your libraries, using either the PRINTIBM.OBJ
  1832.             or PRINTPRO.OBJ object module in place of PRINTEPS.OBJ.
  1833.  
  1834.  
  1835. KEYFLAGS
  1836.  
  1837. Returns a 16-bit unsigned number which is bit-encoded with the current
  1838. status of the CTRL, ALT, INSERT and other keyboard control keys.
  1839.  
  1840. No calling parameters are required.
  1841.  
  1842. DECLARE FUNCTION KeyFlags% ()
  1843.  
  1844. The BITTEST function (see below) can be used to isolate individual bits of
  1845. the returned value. Their meanings are as follows:
  1846.  
  1847.  F E D C B A 9 8 7 6 5 4 3 2 1 0   Bits
  1848. ┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┐
  1849. │0│0│0│0│0│0│0│0│0│0│0│0│0│0│0│0│  Meaning if set
  1850. └─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
  1851.  │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─┴─  Left & Right SHIFT keys pressed
  1852.  │ │ │ │ │ │ │ │ │ │ │ │ │ └─────  CTRL key pressed
  1853.  │ │ │ │ │ │ │ │ │ │ │ │ └───────  ALT key pressed
  1854.  │ │ │ │ │ │ │ │ │ │ │ └─────────  SCROLL LOCK active
  1855.  │ │ │ │ │ │ │ │ │ │ └───────────  NUM LOCK active
  1856.  │ │ │ │ │ │ │ │ │ └─────────────  CAPS LOCK active
  1857.  │ │ │ │ │ │ │ │ └───────────────  INSERT key status
  1858.  │ │ │ │ │ │ │ └─────────────────  Left CTRL key pressed
  1859.  │ │ │ │ │ │ └───────────────────  Left ALT key pressed
  1860.  │ │ │ │ │ └─────────────────────  SYS REQ key pressed
  1861.  │ │ │ │ └───────────────────────  PAUSE (or CTRL-NUM LOCK) active 
  1862.  │ │ │ └─────────────────────────  SCROLL LOCK pressed
  1863.  │ │ └───────────────────────────  NUM LOCK pressed
  1864.  │ └─────────────────────────────  CAPS LOCK pressed
  1865.  └───────────────────────────────  INSERT key pressed
  1866.  
  1867. See the CAPSLOCK, NUMLOCK and SCRLOCK functions for a method of setting or
  1868. reading the status of specific control keys.
  1869.  
  1870.  
  1871. KEYFLUSH
  1872.  
  1873. This procedure flushes the keyboard type-ahead buffer and discards any
  1874. keystrokes which have not yet been processed.
  1875.  
  1876. No calling parameters are required.
  1877.  
  1878. DECLARE SUB KeyFlush ()
  1879.  
  1880. Note:       KEYFLUSH may not work properly if you have installed
  1881.             keystroke enhancement software which moves the type-ahead
  1882.             buffer to another location in memory. It DOES work with
  1883.             command-line buffers like IBM's DOSEDIT, however.
  1884.  
  1885.  
  1886. KEYIN
  1887.  
  1888. Similar to the QuickBASIC INKEY$ function, except that it waits for a
  1889. keypress instead of returning at once if none is available.
  1890.  
  1891. No calling parameters are required.
  1892.  
  1893. DECLARE FUNCTION KeyIn% ()
  1894.  
  1895. The function returns a numeric value between 0 and 255 which represents
  1896. the ASCII code of the key pressed. If one of the function keys (F1 to F12)
  1897. or a special key such as PAGEUP or one of the cursor arrows is pressed,
  1898. then a negative value is returned. Converting this number to its absolute
  1899. equivalent produces the scan code of the key.
  1900.  
  1901. Example:  KeyPress% = KeyIn%
  1902.           IF KeyPress% < 0 THEN
  1903.              ScanCode% = ABS(KeyPress%)
  1904.           ELSE
  1905.              AsciCode% = KeyPress%
  1906.           END IF
  1907.  
  1908. See the ASCICODE topic for a list of ASCII codes and their equivalent
  1909. printable characters. The SCANCODE topic lists the scan codes returned by
  1910. the various function and control keys.
  1911.  
  1912. The KEYIN function will recognise if one of the new 101/102 extended
  1913. keyboards is being used and return the correct scan codes for the extra
  1914. keys such as F11 and F12.
  1915.  
  1916.  
  1917. KEYSTAT
  1918.  
  1919. This function tests to see if a keystroke is waiting to be read. It does
  1920. not read or remove the keystroke from the typeahead buffer, use KEYIN% or
  1921. INKEY$ to do this.
  1922.  
  1923. No calling parameters are required.
  1924.  
  1925. DECLARE FUNCTION KeyStat% ()
  1926.  
  1927. KEYSTAT returns -1 (logical TRUE) if a keystroke is waiting to be
  1928. collected or 0 (logical FALSE) if the typeahead buffer is empty.
  1929.  
  1930.  
  1931. LASTWORD
  1932.  
  1933. Extracts the last word from a string.
  1934.  
  1935. DECLARE FUNCTION LastWord$ (Source$)
  1936.  
  1937. This function extracts the last complete word from a string of
  1938. text and replaces its characters, in the source string, with blank
  1939. spaces. The length of the source string is not altered. LASTWORD
  1940. can be called repeatedly to extract each word until SOURCE$ is 
  1941. empty.
  1942.  
  1943. Example:
  1944.  
  1945. ' LASTEST.BAS
  1946. '
  1947.     DECLARE FUNCTION LastWord$ (Last$)
  1948.  
  1949.     CLS
  1950.     Source$ = "   The moving finger writes and, having writ..  "
  1951.  
  1952.     LOCATE 10, 1
  1953.     PRINT TAB(30); "<"; Source$
  1954.    
  1955.     DO
  1956.        A$ = LastWord$(Source$)
  1957.        PRINT "["; A$; "]"; TAB(30); "<"; Source$
  1958.     LOOP UNTIL A$ = ""
  1959.     PRINT
  1960. END
  1961.  
  1962. See also NEXTWORD (below) which succesively extracts the first word
  1963. from a supplied string.
  1964.  
  1965.  
  1966. LEGALNAME
  1967.  
  1968. This function returns TRUE or FALSE to indicate if the filespec passed to
  1969. it is legal. To do this, each character in the string is compared with a
  1970. set of illegal characters. If none are found a further check is made to
  1971. ensure there are no more than eight characters in the name and three in
  1972. the extension.
  1973.  
  1974. FUNCTION LegalName% (FileSpec$)
  1975.  
  1976.  
  1977. LINEUP
  1978.  
  1979. Returns a string representation of a numeric value. If COMMA% is TRUE
  1980. (non-zero) then the string has commas inserted between every group of
  1981. three digits to the left of the decimal. If LENGTH% is non-zero then the
  1982. resulting string is left padded with spaces to produce a string of the
  1983. required length. If CURRENCY$ is not null, the character it contains will
  1984. be prefixed to the returned string.
  1985.  
  1986. DECLARE FUNCTION LineUp$ (Num#, Places%, Comma%, Length%, Currency$)
  1987.  
  1988.  
  1989. LOBYTE
  1990.  
  1991. Returns the value contained in the Least Significant Byte (LSB) of a
  1992. two-byte integer. This is effectively the remainder obtained after
  1993. dividing the number by 256 (Number% MOD 256).
  1994.  
  1995. DECLARE FUNCTION LoByte% (BYVAL Number%)
  1996.  
  1997. See HIBYTE for a function which returns the Most Significant Byte
  1998. (MSB) of an integer.
  1999.  
  2000.  
  2001. LONGDATE
  2002.  
  2003. This function accepts a three-part numeric date and transcribes it into
  2004. a string containing the date in words. This includes the day of the week,
  2005. which is obtained by calling DOS's internal time and date services. DOS
  2006. is also used to check for an invalid date.
  2007.  
  2008. DECLARE FUNCTION LongDate$(Dy%, Mnth%, Yr%)
  2009.  
  2010. LONGDATE returns a null string if the arguments passed evaluate to an
  2011. illegal date (eg 29/2/1989).
  2012.  
  2013.  
  2014. LONGEST
  2015.  
  2016. Returns the longest word of a string.
  2017.  
  2018. DECLARE FUNCTION Longest$ (Source$)
  2019.  
  2020. This function scans the supplied string of text and returns the
  2021. longest complete word from it. If more than one word is of that
  2022. length, LONGEST returns the first word which meets this criterion.
  2023. If SOURCE$ is null or contains only blank spaces, LONGEST will
  2024. return a null string.
  2025.  
  2026. The word is not removed from the original string.
  2027.  
  2028.  
  2029. LOWORD
  2030.  
  2031. Returns the value contained in the Least Significant Word (LSW) of a
  2032. four-byte long integer. This is effectively the remainder obtained
  2033. after dividing the number by 65536 (Number% MOD 65536).
  2034.  
  2035. DECLARE FUNCTION LoWord% (BYVAL Number&)
  2036.  
  2037. See HIWORD for a function which returns the Most Significant Word
  2038. (MSW) of a long integer.
  2039.  
  2040.  
  2041. LPTSWAP
  2042.  
  2043. This procedure swaps the port addresses of the two printer channels
  2044. specified so that, for example, all output targeted to LPT1: will actually
  2045. be sent to LPT4:, and vice-versa.
  2046.  
  2047. DECLARE SUB LptSwap (BYVAL Prntr1%, BYVAL Prntr2%)
  2048.  
  2049. Prntr1% and Prntr2% are both numeric values in the range 1 - 4, where
  2050. 1 = LPT1:, 2 = LPT2:, etc.
  2051.  
  2052. Note:       any changes made using LPTSWAP will remain in effect 
  2053.             even after your program is finished.
  2054.  
  2055.  
  2056. MASTRENV
  2057.  
  2058. Gets a pointer to the segment of the DOS Master Environment.
  2059.  
  2060. DECLARE FUNCTION MastrEnv% ()
  2061.  
  2062. The QuickBASIC ENVIRON and ENVIRON$ routines allow you to read or set
  2063. variables in the copy of the environment which DOS attaches to your
  2064. program when it starts up. However, because this is only a copy, any
  2065. changes you make to environment variables are lost when the current
  2066. program shuts down. If you want any changes made to variables to be
  2067. passed on to subsequent programs, then you need to make them to DOS's
  2068. Master Environment, which is maintained in low memory.
  2069.  
  2070. This function uses an undocumented interrupt service to obtain the
  2071. address of the first Memory Control Block (MCB) and then follows the
  2072. chain until the Master Environment segment is located. If it fails
  2073. to find it, then a value of zero is returned.
  2074.  
  2075. Once the Master Environment segment is found, your are responsible
  2076. for reading or making any changes to it. Use the FARPEEK and FARPOKE
  2077. routines for this, but proceed with caution. Any changes you make
  2078. will remain in effect until the host computer is rebooted.
  2079.  
  2080.  
  2081. MATCH
  2082.  
  2083. Returns the starting position of a string of characters within
  2084. a larger string.
  2085.  
  2086. DECLARE FUNCTION Match% (Start%, Search$, Pattern$)
  2087.  
  2088. Call with:  Start%   = character position in search string to
  2089.                        start searching from
  2090.             Search$  = String to search
  2091.             Pattern$ = String expression to search for 
  2092.  
  2093. Returns:    Position of first character of Pattern$ in Search$
  2094.             (0 if Pattern$ is not found)
  2095.  
  2096. Wildcards:  #   match any numeric character
  2097.             !   match any alphabetic character
  2098.             ?   match any character
  2099.  
  2100.             \   indicates that the next character in the string
  2101.                 to search for is literal, not a wildcard.
  2102.  
  2103. This function is similar to INSTR but allows the use of wildcards. It is
  2104. based on the MATCH function provided by Digital Research's C-BASIC.
  2105.  
  2106.  
  2107. MATHSCHIP
  2108.  
  2109. Checks to see if a floating-point maths co-processor is installed in the
  2110. system. 
  2111.  
  2112. No calling parameters are required.
  2113.  
  2114. DECLARE FUNCTION MathsChip% ()
  2115.  
  2116. MATHSCHIP returns 0 (logical FALSE) if no co-processor is available. A
  2117. non-zero value indicates that a co-processor is available and, in this
  2118. case, the function will attempt to identify it. Possible return values
  2119. are:
  2120.  
  2121.      87 =   Intel 8087
  2122.     287 =   Intel 80287
  2123.     387 =   Intel 80387 (or 80486 with built-in maths processor)
  2124.  
  2125. Waitek and other models return the same values as their Intel equivalents.
  2126.  
  2127.  
  2128. MCGACOPY
  2129.  
  2130. Copies an MCGA screen to or from a user-supplied dynamic array.
  2131.  
  2132. DECLARE SUB McgaCopy (BYVAL Switch%, BYVAL Segment%, BYVAL Offset%)
  2133.  
  2134. SWITCH%     Direction of copy   0 = copy screen to string
  2135.                                 1 = copy string to screen
  2136.  
  2137. SEGMENT%    Segment address of storage array.
  2138.  
  2139. OFFSET%     Offset address of storage array.          
  2140.  
  2141. ARRAY       Dynamic INTEGER or LONG integer array to hold the screen
  2142.             image. It must contain at least 64000 bytes of storage
  2143.             (32000 elements for INTEGER or 16000 for LONG) or the
  2144.             routine will fail, with possibly disastrous results.
  2145.  
  2146. Note:       It is not enough just to pass the name of the storage
  2147.             array to MCGACOPY. You must explicitly name the element
  2148.             where screen storage is to start, eg:
  2149.  
  2150.             DIM ScreenArray(1 TO 32000) AS INTEGER
  2151.             SCREEN 13
  2152.                 .
  2153.             draw some stuff
  2154.                 .
  2155.             McgaCopy 0, VARSEG(ScreenArray(1)), VARPTR(ScreenArray(1))
  2156.  
  2157.  
  2158. The QuickBASIC PCOPY statement is very useful for storing screen pages in
  2159. memory, so that they can be kept out of sight until needed. Unfortunately
  2160. it only works in text modes or, on computers with EGA or VGA video cards,
  2161. in SCREEN modes 7 to 12. This routine, on the other hand, works only in
  2162. the MCGA display mode (SCREEN 13), it provides a useful alternative to the
  2163. PCOPY statement for use with medium-resolution 256-colour screens.
  2164.  
  2165. See CGACOPY for a version that can be used with SCREEN 1 and 2 displays.
  2166.  
  2167.  
  2168. MCGASCROLL
  2169.  
  2170. Scrolls a rectangular portion of a SCREEN 13 (320 x 200 256-colour)
  2171. display one pixel to the left or right, wrapping those pixels which are
  2172. scrolled out at the end round to the beginning again.
  2173.  
  2174. DECLARE SUB McgaScroll (BYVAL xLoc%, BYVAL yLoc%, BYVAL xPixels%,_
  2175.                         BYVAL yPixels%, BYVAL Direction%)                 
  2176.  
  2177. XLOC%       The horizontal (X) co-ordinate of the top-left corner of
  2178.             the rectangle to be scrolled.
  2179.  
  2180. YLOC%       The vertical (Y) co-ordinate of the top-left corner of
  2181.             the rectangle to be scrolled.
  2182.  
  2183. XPIXELS%    The width (in pixels) of the rectangle to be scrolled.
  2184.  
  2185. YPIXELS%    The height (in pixels) of the rectangle to be scrolled.
  2186.  
  2187. DIRECTION%  The direction in which the rectangle contents are to be
  2188.             scrolled (0 = Left, 1 = Right).
  2189.  
  2190. Co-ordinates are in the ranges:  X >= 0 <= 319, Y >= 0 <= 199
  2191.  
  2192.  
  2193. MCGATEXT
  2194.  
  2195. Writes characters to the screen in the 320 x 200  256-colour graphics
  2196. mode (SCREEN 13).
  2197.  
  2198. DECLARE SUB McgaText (BYVAL xLoc%, BYVAL yLoc%, Text$,_
  2199.                       BYVAL Attr%, BYVAL Scale%)
  2200.  
  2201. This routine provides a convenient way of displaying text in SCREEN 13
  2202. without having to bother about loading external font files. It uses the
  2203. standard character definition tables built into your display adaptor, but
  2204. allows you to scale them up to eight times normal size and to specify any
  2205. combination of foreground and background colours.
  2206.  
  2207. XLOC%       The horizontal co-ordinate of the top left hand pixel
  2208.             from which the text will begin (0 - 319).
  2209.  
  2210. YLOC%       The vertical co-ordinate of the top left hand pixel
  2211.             from which the text will begin (0 - 199).
  2212.  
  2213. TEXT$       The string of text to be displayed (up to 63 characters).
  2214.  
  2215. ATTR%       The colour (or display attribute in monochrome modes) to
  2216.             be given to the text. This is calculated by the formula:
  2217.  
  2218.             Colour% = (Background% * 256) + Foreground%
  2219.  
  2220.             Foreground is in the range (0 - 255) and Background (0 - 64).
  2221.             The actual colours displayed depend upon your current PALETTE
  2222.             settings.
  2223.  
  2224.             Note:   supplying a value of -1 for background prevents
  2225.                     background pixels from being changed at all. This
  2226.                     allows text to be blended more naturally into a
  2227.                     complex graphics display.
  2228.  
  2229. SCALE%      The character size of the text to be displayed. This ranges
  2230.             from 1 to 8, where 1 is standard 40-column text and where 8
  2231.             multiplies the character size by eight on both the horizontal
  2232.             and vertical axes.
  2233.  
  2234. The complete extended ASCII character set is supported, including foreign
  2235. symbols and box-drawing characters.
  2236.  
  2237. Since MCGATEXT does not support clipping, to ensure a clean display you
  2238. must ensure that the text to be output fits within the current screen
  2239. boundaries.
  2240.  
  2241. See also CGATEXT for displaying characters in SCREEN 1 and VGATEXT for
  2242. displaying characters in SCREENs 7-12.
  2243.  
  2244.  
  2245. MEDIA
  2246.  
  2247. Gets or sets the volume label and/or serial number of the specified
  2248. disk drive. Also returns the file system (FAT) type. This procedure
  2249. only works with DOS 5.0 or greater.
  2250.  
  2251. DECLARE SUB Media (Set%, Drive$, Volume$, Serial$, FileSy$)
  2252.  
  2253. Set%    =   FALSE (zero) Get media information.
  2254.             TRUE (non-zero) Set media information.
  2255. Drive$  =   The drive letter of the disk to be processed. A colon
  2256.             may be included although it is not necessary. If Drive$
  2257.             is a null string then the default, currently-logged, 
  2258.             drive is assumed.
  2259. Volume$ =   The disk volume label (maximum 11 characters). If this
  2260.             is a null string and Set% = TRUE, then the existing label
  2261.             is not changed. To blank out an existing volume label,
  2262.             fill Volume$ with at least one ASCII space character,
  2263. Serial$ =   The disk serial number (8 hexadecimal characters). If
  2264.             this is a null string and Set% = TRUE, then the existing
  2265.             serial number is not changed. When setting a new serial
  2266.             number do not include the intervening colon.
  2267. FileSy$ =   The file system in use on the specified drive. Under DOS 5
  2268.             this is either 12-bit or 16-bit FAT. Provided for information
  2269.             only, you cannot change it except by reformatting the drive.
  2270.  
  2271. Note that the Volume Label is the one written that is written into the
  2272. Boot Record when the disk is formatted and is not necessarily the same
  2273. as the one set or returned by the DOS LABEL command.
  2274.  
  2275.  
  2276. MISTAKE
  2277.  
  2278. Displays the error message supplied in a dialogue box and waits for the
  2279. operator to press the <ENTER> key before returning, restoring the screen
  2280. to its' previous state.
  2281.  
  2282. DECLARE SUB MisTake (BYVAL Row%, Message$, BYVAL Attr%, BYVAL Mouse%)
  2283.  
  2284. ROW%        The top row of the dialogue box when it is displayed. The
  2285.             box is automatically centered within this row, which may be
  2286.             adjusted so that it remains within the screen boundaries.
  2287.  
  2288. MESSAGE$    A string of text comprising the error message to be displayed.
  2289.             It must be no longer than 40 characters otherwise it will be
  2290.             truncated to fit inside the display panel.
  2291.  
  2292. ATTR%       The display attribute or colour to be given to the dialogue box.
  2293.             If an argument of zero is supplied, the box is displayed with
  2294.             bright yellow foreground on a red background (colour monitors)
  2295.             or in reverse video (monochrome monitors). On colour displays the
  2296.             message text is always given a white foreground, no matter what
  2297.             attribute is specified.
  2298.  
  2299. MOUSE%     Should be set to TRUE (-1) or FALSE (0) to indicate if a
  2300.             mouse is available for use. If available, the operator can
  2301.             respond by clicking the left mouse button while the cursor is
  2302.             positioned on the radio button.     
  2303.  
  2304. This routine is a special case of the INFORM dialogue box procedure (see
  2305. above) which can be used for any general-purpose messages which require an
  2306. acknowledgement from the operator.
  2307.  
  2308.  
  2309. MOUSEBORDER
  2310.  
  2311. Sets the maximum and minimum boundaries for mouse movement, both
  2312. horizontally and vertically.
  2313.  
  2314. DECLARE SUB MouseBorder (BYVAL x1%, BYVAL y1%, BYVAL x2%, BYVAL y2%)
  2315.  
  2316. This routine defines a screen rectangle into which the mouse cursor
  2317. is confined. x1% - y1% are the pixel co-ordinates of the upper-left
  2318. corner and x2% - y2% the pixel co-ordinates of the lower-right. If
  2319. the upper-left co-ordinates are greater than the lower-right then
  2320. the two sets of values will be swapped.
  2321.  
  2322. If the current mouse pointer is outside the defined rectangle, then
  2323. it will be moved inside it.
  2324.  
  2325.  
  2326. MOUSEHIDE
  2327.  
  2328. Make the mouse cursor invisible. 
  2329.  
  2330. DECLARE SUB MouseHide ()
  2331.  
  2332.  
  2333. MOUSEINIT
  2334.  
  2335. Initialises the mouse driver and returns the driver status. Also hides
  2336. the mouse cursor if it was previously visible.
  2337.  
  2338. DECLARE FUNCTION MouseInit% ()
  2339.  
  2340. Returns TRUE (-1) if mouse support is available or FALSE (0) if not.
  2341.  
  2342.  
  2343. MOUSEMICKEY
  2344.  
  2345. Read mouse motion counters.
  2346.  
  2347. Return the number of horizontal and vertical mickeys moved since the
  2348. last mouse function call.
  2349.  
  2350. DECLARE SUB MouseMickey (horizontal%, vertical%)
  2351.  
  2352. The returned values represent the net mouse pointer displacement since
  2353. this routine was last called. A positive number indicates movement to
  2354. the right or downward. Negative values indicate travel to the left or
  2355. upwards. One mickey is approximately 1/200" of mouse movement.
  2356.  
  2357.  
  2358. MOUSENOW
  2359.  
  2360. Returns the current state of the mouse.
  2361.  
  2362. DECLARE SUB MouseNow (leftButton%, rightButton%, xMouse%, yMouse%)
  2363.  
  2364. If leftButton% or rightButton% are TRUE (-1) than that button is
  2365. currently being pressed, otherwise they are set to FALSE (0).
  2366. xMouse% and yMouse% contain the current horizontal and vertical 
  2367. pixel co-ordinates of the mouse pointer.
  2368.  
  2369.  
  2370. MOUSEPRESSLEFT
  2371.  
  2372. Returns the mouse state at the last press of the left button.
  2373.  
  2374. DECLARE SUB MousePressLeft (leftCount%, xMouse%, yMouse%)
  2375.  
  2376. leftCount% returns the number of presses that have been made on the 
  2377. left mouse button since this routine was last called. xMouse% and
  2378. yMouse% contain the horizontal and vertical pixel co-ordinates of
  2379. the mouse pointer at the last button press (left or right).
  2380.  
  2381. Calling this procedure resets the left button press counter to zero.
  2382.  
  2383.  
  2384. MOUSEPRESSRIGHT
  2385.  
  2386. Returns the mouse state at the last press of the right button.
  2387.  
  2388. DECLARE SUB MousePressRight (rightCount%, xMouse%, yMouse%)
  2389.  
  2390. rightCount% returns the number of presses that have been made on the 
  2391. right mouse button since this routine was last called. xMouse% and
  2392. yMouse% contain the horizontal and vertical pixel co-ordinates of
  2393. the mouse pointer at the last button press (left or right).
  2394.  
  2395. Calling this procedure resets the right button press counter to zero.
  2396.  
  2397.  
  2398. MOUSEPUT
  2399.  
  2400. Sets the mouse cursor position.
  2401.  
  2402. DECLARE SUB MousePut (BYVAL xMouse%, BYVAL yMouse%)
  2403.  
  2404. xMouse% and yMouse% are the horizontal and vertical pixel co-ordinates
  2405. of the screen location where the mouse pointer is to be moved. This
  2406. position is adjusted, if necessary, to lie within the limits specified
  2407. by a previous call to MOUSEBORDER (see above).
  2408.  
  2409.  
  2410. MOUSERELLEFT
  2411.  
  2412. Returns the mouse state at the last release of the left mouse button.
  2413.  
  2414. DECLARE SUB MouseRelLeft (leftCount%, xMouse%, yMouse%)
  2415.  
  2416. leftCount% returns the number of times the left mouse button has been
  2417. released since this procedure was last called. xMouse% and yMouse%
  2418. contain the horizontal and vertical pixel co-ordinates of the mouse
  2419. pointer at the last button release (left or right).
  2420.  
  2421. Calling this routine resets the left button release counter to zero.
  2422.  
  2423.  
  2424. MOUSERELRIGHT
  2425.  
  2426. Returns the mouse state at the last release of the right mouse button.
  2427.  
  2428. DECLARE SUB MouseRelRight (rightCount%, xMouse%, yMouse%)
  2429.  
  2430. rightCount% returns the number of times the right mouse button has been
  2431. released since this procedure was last called. xMouse% and yMouse%
  2432. contain the horizontal and vertical pixel co-ordinates of the mouse
  2433. pointer at the last button release (left or right).
  2434.  
  2435. Calling this routine resets the right button release counter to zero.
  2436.  
  2437.  
  2438. MOUSERESTORE
  2439.  
  2440. Restores the mouse pointer to the position and state that was in
  2441. effect at the previous call to MOUSESAVE (see below).
  2442.  
  2443. DECLARE SUB MouseRestore ()
  2444.  
  2445.  
  2446. MOUSESAVE
  2447.  
  2448. Saves the current mouse pointer state and screen location in an
  2449. internal buffer.
  2450.  
  2451. DECLARE SUB MouseSave ()
  2452.  
  2453. The MOUSERESTORE procedure (see above) can be used to restore
  2454. the mouse pointer state.
  2455.  
  2456.  
  2457. MOUSESHOW
  2458.  
  2459. Makes the mouse cursor visible.
  2460.  
  2461. DECLARE SUB MouseShow ()
  2462.  
  2463.  
  2464. MOUSESPEED
  2465.  
  2466. Sets the mouse mickeys to pixels ratio.
  2467.  
  2468. DECLARE SUB MouseSpeed (BYVAL horizontal%, BYVAL vertical%)
  2469.  
  2470. Sets the number of mickeys that are equivalent to 8 screen pixels for
  2471. horizontal and vertical mouse movement. One mickey is approximately
  2472. 1/200" of physical mouse motion.
  2473.  
  2474.  
  2475. MOUSEWARP
  2476.  
  2477. Set the double-speed threshold.
  2478.  
  2479. DECLARE SUB MouseWarp (BYVAL threshold%)
  2480.  
  2481. Defines the threshold for doubling the speed of mouse pointer travel.
  2482. The threshold% value is supplied in mickeys/second (default = 64).
  2483. Doubling of pointer speed can be effectively disabled by setting the
  2484. threshold to a very large value (such as 32,767).
  2485.  
  2486.  
  2487. NETTEST
  2488.  
  2489. This function is used to detect if the program which calls it is running
  2490. under a Novell Network. It can be used to decide if file or record locking
  2491. is required.
  2492.  
  2493. No calling parameters are required.
  2494.  
  2495. DECLARE FUNCTION NetTest% ()
  2496.  
  2497. Returns -1 (logical TRUE) if the Network shell is present and 0 (logical
  2498. FALSE) if not. Note that the function cannot distinguish between programs
  2499. running on a local or network drive under NetWare.
  2500.  
  2501. The SHARING function (below) provides similar information for file-sharing
  2502. using DOS's SHARE.EXE program.
  2503.  
  2504.  
  2505. NEXTWORD
  2506.  
  2507. Extracts the first word from a string.
  2508.  
  2509. DECLARE FUNCTION NextWord$ (Source$)
  2510.  
  2511. This function extracts the first complete word from a string of
  2512. text and replaces its characters, in the source string, with blank
  2513. spaces. The length of the source string is not altered. NEXTWORD
  2514. can be called repeatedly to extract each word until SOURCE$ is 
  2515. empty.
  2516.  
  2517. Example:
  2518.  
  2519. ' NEXTEST.BAS
  2520. '
  2521.     DECLARE FUNCTION NextWord$ (Last$)
  2522.  
  2523.     CLS
  2524.     Source$ = "   The moving finger writes and, having writ..  "
  2525.  
  2526.     LOCATE 10, 1
  2527.     PRINT TAB(30); "<"; Source$
  2528.    
  2529.     DO
  2530.        A$ = NextWord$(Source$)
  2531.        PRINT "["; A$; "]"; TAB(30); "<"; Source$
  2532.     LOOP UNTIL A$ = ""
  2533.     PRINT
  2534. END
  2535.  
  2536. See also LASTWORD (above) which succesively extracts the last word
  2537. from a supplied string.
  2538.  
  2539.  
  2540. NUMBERDAY
  2541.  
  2542. Splits a Julian date number into day, month and year and also returns the
  2543. day of the week as a number between 0 and 6 (0 = Sunday etc..)
  2544.  
  2545. DECLARE FUNCTION NumberDay% (Number&, Dy%, Mnth%, Yr%)
  2546.  
  2547.  
  2548. NUMLOCK
  2549.  
  2550. Toggles NUM LOCK on or off or, alternatively, reads the current NUM LOCK
  2551. key setting.
  2552.  
  2553. DECLARE FUNCTION NumLock% (BYVAL Switch%)
  2554.  
  2555. Switch% = 0  Turns NUM LOCK off
  2556.         = 1  Turns NUM LOCK on
  2557.  
  2558. Any other value just returns the current NUM status as a logical value
  2559. where -1 (TRUE) means that NUM LOCK is on and 0 (FALSE) means that NUM
  2560. LOCK is off.
  2561.  
  2562.  
  2563. PANEL
  2564.  
  2565. This procedure is used to produce rectangular boxes, upon the video
  2566. display, of various shapes and colours. The calling program should supply
  2567. the row/column co-ordinate of the top, left-hand corner of the required
  2568. panel, its height in rows and width in columns. You should also specify
  2569. the display attribute that the panel will be displayed in and the border
  2570. style to frame it with.
  2571.  
  2572. DECLARE SUB Panel (Row%, Col%, Rows%, Cols%, Border%, Attr%)
  2573.  
  2574. Panels can be drawn with the following border styles:
  2575.  
  2576. ┌───┐         ╔═══╗         ╓───╖        ╒═══╕
  2577. │ 1 │         ║ 2 ║         ║ 3 ║        │ 4 │
  2578. └───┘         ╚═══╝         ╙───╜        ╘═══╛
  2579.  
  2580. This version of the Toolbox allows you to use PANEL to draw boxes with
  2581. a sculptured, three-dimensional look. Do this by adding a multiple of
  2582. four to the border style you want. Legal values are.....
  2583.  
  2584. Border%       Description
  2585.  
  2586.  5 - 8        Draws box in high relief with light appearing to come 
  2587.               from the upper left of the screen.
  2588.  
  2589.  9 - 12       Draws box in low relief with light coming from upper
  2590.               left. This makes the box appear to be recessed.
  2591.  
  2592. 13 - 16       Draws box in high relief with light coming from upper
  2593.               right of screen.
  2594.  
  2595. 17 - 20       Draws box in low relief with light coming from upper
  2596.               right of screen.
  2597.  
  2598. Any other value draws the panel without a border.
  2599.  
  2600. Example:
  2601.  
  2602. ' PANLTEST.BAS
  2603. '
  2604.     DECLARE SUB Panel (Row%, Col%, Rows%, Cols%, Border%, Attr%)
  2605.  
  2606.     CLS
  2607.     Colour% = 112: Protrude% = 5: Depress% = 9
  2608.     Panel 5, 25, 14, 30, Protrude%, Colour%
  2609.     Panel 7, 27, 3, 26, Depress%, Colour%
  2610.     Col% = 27
  2611.     FOR I% = 1 TO 3
  2612.         Panel 11, Col%, 2, 8, Protrude%, Colour%
  2613.         Panel 13, Col%, 2, 8, Protrude%, Colour%
  2614.         Panel 15, Col%, 2, 8, Protrude%, Colour%
  2615.         Col% = Col% + 9
  2616.     NEXT I%
  2617.     Panel 13, 36, 2, 8, Depress%, Colour%
  2618. END
  2619.  
  2620. Although the boxes drawn by PANEL resemble popup windows, you cannot
  2621. restore the screen contents overwritten by a box once it has been drawn.
  2622. See the POPUP and SHUTUP routines, however, for a full windowing
  2623. system which does preserve the display.
  2624.  
  2625.  
  2626. PARALLELPORTS
  2627.  
  2628. This function checks how many hardware printer ports are available. It
  2629. does not check to see if an actual printer is connected to each of them,
  2630. use the PRINTEST or PRINTERSTAT functions (see below) to obtain this
  2631. information.
  2632.  
  2633. No calling parameters are required.
  2634.  
  2635. DECLARE FUNCTION ParallelPorts% ()
  2636.  
  2637.  
  2638. PARKHEADS
  2639.  
  2640. Parks the heads of each fixed disk drive in the system onto the last
  2641. cylinder of the disk, preparatory to powering off.
  2642.  
  2643. DECLARE SUB ParkHeads ()
  2644.  
  2645. This routine only works reliablly on AT class computers and above.
  2646. Using it on an XT may simply cause the computer to 'hang', without
  2647. parking the heads.
  2648.  
  2649.  
  2650. PAUSE
  2651.  
  2652. This routine is used to generate machine-independent timing loops. It
  2653. simply pauses until the specified number of clock ticks have elapsed.
  2654.  
  2655. DECLARE SUB Pause (BYVAL Ticks%)
  2656.  
  2657. There are 18.2 clock ticks per second on all PCs, no matter what the
  2658. processor or processor speed.
  2659.  
  2660.  
  2661. PEEKWORD
  2662.  
  2663. Reads a long integer value from two consecutive bytes of memory.
  2664.  
  2665. DECLARE FUNCTION PeekWord& (BYVAL Segment&, BYVAL Offset&)
  2666.  
  2667. Arguments:  Segment&  = address of memory segment containing the data
  2668.                         to be read.
  2669.             Offset&   = offset address, within the segment of the 
  2670.                         two bytes to be read.
  2671.  
  2672. Returns:    contents of the two consecutive bytes in the form of a
  2673.             long integer value in the range (0 to 65535). 
  2674.  
  2675. Note:       parameters are passed as LONG integers to save you the
  2676.             hassle of having to convert argument values over 32767
  2677.             to negative signed integers. Do not use values greater
  2678.             than 65535, however, or the most significant word will
  2679.             be ignored and the address converted to Modulus 65536.
  2680.  
  2681.             If you supply an offset address of 65535 (0FFFFh) which
  2682.             would cause the second byte to cross a segment boundary,
  2683.             only the lower byte is read and returned as a value
  2684.             between (0 - 255).
  2685.  
  2686. Using QuickBASIC's PEEK function to examine data which lies outside
  2687. of DGROUP is a pain. You also have to use DEF SEG to set the segment
  2688. required and then to reset it afterwards. This function allows you to
  2689. read data, directly, from anywhere in the 1 megabyte of addressable
  2690. RAM space your computer contains. It also reads two adjacent bytes of
  2691. data from the address supplied and converts them to a single integer.
  2692.  
  2693. The PC architecture follows the Intel convention of storing 'words'
  2694. (two-byte values) with the Least Significant part in the lower byte
  2695. (LSB) and the Most Significant (MSB) in the higher byte. Since each
  2696. byte can only hold 256 possible values (0 to 255), an integer which
  2697. has a range of from 0 to 65535 (unsigned) is stored in consecutive
  2698. bytes with the MSB being considered the number of times it can be
  2699. divided by 256 and the LSB being the remainder of this division. The
  2700. number 1000, for example would be stored in memory as follows:
  2701.  
  2702.                          LSB              MSB
  2703.                  ┌─┬─┬─┬─┬─┬─┬─┬─┐ ┌─┬─┬─┬─┬─┬─┬─┬─┐
  2704. 1000 (decimal) = │1│1│1│0│1│0│0│0│ │0│0│0│0│0│0│1│1│
  2705.                  └─┴─┴─┴─┴─┴─┴─┴─┘ └─┴─┴─┴─┴─┴─┴─┴─┘
  2706.  
  2707.                  1000 MOD 256 = 232   1000 \ 256 = 3
  2708.  
  2709. To convert the two bytes back to a single integer again, you would
  2710. use the formula: 
  2711.  
  2712.                         x = (MSB * 256) + LSB 
  2713.  
  2714. or, in our example:     x = 3 * 256 + 232 = 1000
  2715.  
  2716. PEEKWORD makes this conversion for you automatically, all you have to
  2717. do is supply the address and it returns the contents of the two bytes
  2718. in long integer format.
  2719.  
  2720. The POKEWORD procedure (below) complements PEEKWORD by allowing you
  2721. to write a word of data anywhere in the 1MB addressable PC workspace.
  2722.  
  2723. See also FARPEEK and FARPOKE which allow you to read from and write
  2724. to far memory, one byte at a time.
  2725.  
  2726.  
  2727. PERCENTBOX
  2728.  
  2729. Opens and maintains a popup window which displays a percentage value
  2730. as a horizontal bar.
  2731.  
  2732. DECLARE SUB PerCentBox (BYVAL Switch%, Message$, BYVAL Attr%,_
  2733.                         BYVAL PerCent%)
  2734.  
  2735. Arguments:  Switch%   = 1  open percentage box window
  2736.                       = 2  maintain percentage bar
  2737.                       = 3  close percentage box
  2738.                       
  2739.             Message$  = an optional message which is centred in the
  2740.                         percentage box window (Switch% = 1).
  2741.                         
  2742.             Attr%     = display colour or attribute for percentage
  2743.                         box window and text. If Attr% = 0 attribute
  2744.                         defaults to 48 (Black on Cyan) for colour
  2745.                         adaptors and 112 (Reverse) for monochrome.
  2746.                         (used only with Switch% = 1)
  2747.                         
  2748.             PerCent%  = an integer value between 0 and 100 which
  2749.                         controls the length of the percentage bar.
  2750.                         (used only with Switch% = 2)            
  2751.  
  2752. Here is another useful little routine for Toolbox users. It pops up a
  2753. window in which is displayed a percentage bar, illustrating how much
  2754. of the current process has been completed. Use it, during lengthy
  2755. operations, to reassure an operator that the program is not 'hanging',
  2756. or to indicate how much longer there is to go.
  2757.  
  2758. The Percentage Box window is popped up, centered, on the screen. It
  2759. recognises 43 and 50 line displays and will adjust itself accordingly.
  2760. Only one Percentage Box can be open at a time, although other windows
  2761. and dialogue boxes may be opened and closed while it is present. Be
  2762. careful not to overlap the Percentage Box with other windows, though.
  2763.  
  2764.  
  2765. PICKLIST
  2766.  
  2767. Allows the user to select from a list of items in a popup window.
  2768.  
  2769. DECLARE SUB PickList (Selected%, Title$, Array() AS STRING, Attr%, Mouse%)
  2770.  
  2771. Title$          The text to be displayed as the title of the
  2772.                 selection box.
  2773.  
  2774. Array()         An array of variable-length strings containing the
  2775.                 text items to be selected from.
  2776.  
  2777. Attr%           The display attribute to be given to the selection
  2778.                 box. If zero the default of reverse video is used.
  2779.  
  2780. Mouse%          If TRUE (non-zero) mouse support is enabled. If 
  2781.                 FALSE (zero) only the keyboard may be used to make 
  2782.                 selections.
  2783.  
  2784. Selected%       On return this variable contains the subscript
  2785.                 number of the string element selected.
  2786.  
  2787. This routine is similar to FINDFILE (above) which uses a picklist to
  2788. enable the user to select from a list of files.
  2789.  
  2790.  
  2791. POKEWORD
  2792.  
  2793. Writes an integer value into two consecutive bytes of memory.
  2794.  
  2795. DECLARE SUB PokeWord (BYVAL Segment&, BYVAL Offset&, BYVAL Word&)
  2796.  
  2797. Arguments:  Segment&  = address of memory segment containing the
  2798.                         location to be written to
  2799.             Offset&   = offset address, within the segment of the 
  2800.                         two bytes to be set.
  2801.             Word&     = the value to set in memory. It must be a
  2802.                         value in the range 0 to 65535.
  2803.  
  2804. The data is written in standard Intel format, with the Most
  2805. Significant part of the number (MSB) being written into the higher
  2806. of the two bytes.
  2807.  
  2808. Note:       if you supply an offset address of 65535 (0FFFFh) which
  2809.             would cause the second byte to cross a segment boundary,
  2810.             only the lower, least significant, byte (LSB) is written.
  2811.  
  2812.             Parameters are passed as LONG integers to save you the
  2813.             hassle of having to convert argument values over 32767
  2814.             to negative signed integers. Do not use values greater
  2815.             than 65535, however, or the most significant word will
  2816.             be ignored and the address converted to Modulus 65536.
  2817.  
  2818. The PEEKWORD procedure (above) complements POKEWORD by allowing you
  2819. to read a word of data from anywhere in the 1MB of addressable PC
  2820. memory.
  2821.  
  2822. See also FARPEEK and FARPOKE which allow you to read from and write
  2823. to far memory, one byte at a time.
  2824.  
  2825.  
  2826. POPUP
  2827.  
  2828. This is the Toolbox popup window generator. What are Windows?  Well if
  2829. you've used the QuickBASIC environment at all then you've used Windows.
  2830. When you press <ALT><F> to bring down the File Menu, the list of options
  2831. presented there is in a window. Notice how any characters which were
  2832. concealed when the File Menu appeared, are restored, intact, after you've
  2833. made your choice. Windows are areas of the screen which are used to hold
  2834. transient data and messages to the user. They make the most of the limited
  2835. display space available and remove the need to constantly rebuild the
  2836. screen, each time your program communicates with the world.
  2837.  
  2838. Properly  presented, windows can give the illusion of multi-tasking, even
  2839. on single-processor machines like the IBM-PC.
  2840.  
  2841. Nowadays, no program worth its' salt can be without a window of some kind.
  2842. If YOUR program is going to stand out amongst all the others, however,
  2843. they've got to be done professionally. Windows must appear instantly and
  2844. vanish, just as quickly, when no longer required. They must be as large or
  2845. as small as is necessary, for the data which you need to display, and you
  2846. should have a plentiful supply, for all the circumstances that your
  2847. program might encounter. BASIC, unfortunately, is just not fast enough to
  2848. meet all these requirements.
  2849.  
  2850. Looks like it'll have to be Assembly-Language again ...
  2851.  
  2852. DECLARE SUB PopUp (BYVAL Row%, BYVAL Col%, BYVAL Hght%, BYVAL Wdth%,_
  2853.                    BYVAL Attr%, BYVAL Brdr%, BYVAL Shdw%, BYVAL Zoom%)
  2854.  
  2855. Opens a popup window at the screen location specified.
  2856.  
  2857. Where:    P1%  is the top-left row co-ordinate
  2858.           P2%  is the top-left column co-ordinate
  2859.           P3%  is the height (in rows) of the window
  2860.           P4%  is the width (in columns) of the window
  2861.           P5%  is the display attribute or colour
  2862.           P6%  is the border style (0 = no border)
  2863.           P7%  is the shadow switch (0 = no shadow)
  2864.           P8%  is the zoom switch (0 = no zoom)
  2865.  
  2866. The first four parameters specify the size of the window and the location
  2867. on the screen at which it will appear. Border styles are as follows:
  2868.  
  2869. ┌────┐
  2870. │ 1. │    Single-lined box all round the window
  2871. └────┘
  2872. ╔════╗
  2873. ║ 2. ║    Double-lined box all round the window
  2874. ╚════╝
  2875. ╒════╕
  2876. │ 3. │    Single vertical, double horizontal
  2877. ╘════╛
  2878. ╓────╖
  2879. ║ 4. ║    Single horizontal, double vertical
  2880. ╙────╜
  2881. ╤════╤
  2882. │ 5. │    Single-lined box all round the window
  2883. ╘════╛
  2884. ╦════╦
  2885. ║ 6. ║    Double-lined box all round the window
  2886. ╚════╝
  2887. ┬────┬
  2888. │ 7. │    Single vertical, double horizontal
  2889. ╘════╛
  2890. ╥────╥
  2891. ║ 8. ║    Single horizontal, double vertical
  2892. ╙────╜
  2893.  
  2894. Border styles 5 through 8 are particularly suitable for use with pull-
  2895. down menus, descending from a horizontal bar.
  2896.  
  2897. The SHADOW switch (Parameter 7), can be used to add a black shadow beneath
  2898. your window, Giving it a three dimensional effect. Setting P7% to 1 puts
  2899. solid shadow on the left-hand side. Setting P7% to 2 puts it on the right.
  2900. values of 3 and 4 in P7% will display transparant shadow to the left or
  2901. right, respectively, any other value prevents shadow.
  2902.  
  2903. Setting Parameter 8 to a non-zero value will cause the window to ZOOM onto
  2904. the screen.  What this means is that, starting at a point source,
  2905. successively larger versions of the window will be drawn until it is the
  2906. size required. The value you supply sets the interval, in milliseconds,
  2907. between iterations and is used to control the speed at which the window
  2908. explodes onto the screen. 
  2909.  
  2910. To preserve compatibility with programs written for use with previous
  2911. versions of the Toolbox, a value of 1 in parameter 8 sets the default
  2912. delay of 20 milliseconds per iteration. At this speed, which is constant
  2913. on PCs with all types of microprocessor, the process is extremely fast
  2914. and impressive, and adds a very professional touch to your programs. 
  2915.  
  2916. Before a window is opened, the display area below it is copied to an
  2917. internal buffer, from where it will be eventually restored when the window
  2918. is closed. This buffer has a capacity of 8 KiloBytes, the equivalent of
  2919. two full screens. To calculate the storage required for a particular
  2920. window, use the formula:
  2921.  
  2922. Bytes = ((Height in rows * Width in columns) * 2) + 6
  2923.  
  2924. (add one row to the height and one column to the width if you specify
  2925. shadow)
  2926.  
  2927. The window area needs to be multiplied by 2 since each screen character
  2928. takes two bytes of memory, for itself and its attribute code. The odd six
  2929. bytes are required for the storage of buffer pointers. The window buffer
  2930. works as a LIFO (Last In First Out) stack, so that the last window opened
  2931. is the first one to be removed. You can close the current window with the
  2932. statement:
  2933.  
  2934. ShutUp -1
  2935.  
  2936. To put text inside a window, use the FASTPRINT routine (see above). You
  2937. can clear all or part of an open window with SCROLL (see below).
  2938.  
  2939.  
  2940. PRINTERSTAT
  2941.  
  2942. DECLARE FUNCTION PrinterStat% (BYVAL Prntr%)
  2943.  
  2944. This function tests the current status of the parallel printer specified.
  2945. The value returned is tested as follows :
  2946.  
  2947.    Bit     Wanted    Meaning
  2948. ─────────────────────────────────────────────────────
  2949.     7        1       Printer not busy (0 = busy)
  2950.     6        0       Printer acknowledges
  2951.     5        0       Out-of-paper
  2952.     4        1       This printer selected
  2953.     3        0       I/O error
  2954.     2        0       Not used
  2955.     1        0       Not used
  2956.     0        0       Time-out occurred
  2957. ─────────────────────────────────────────────────────
  2958.    90 Hex  144 (Decimal)
  2959.  
  2960. Specify the printer to be tested as a number between 1 and 4, where 1 =
  2961. LPT1:, 2 = LPT2:, etc.
  2962.  
  2963. Note:       Some printers also set the acknowledgement bit. If so, the
  2964.             value returned will be 208 (D0 Hex) instead of 144.
  2965.  
  2966.  
  2967. PRINTEST
  2968.  
  2969. This is a simplified version of the PRINTERSTAT function (above). It
  2970. returns a logical value to indicate whether the specified printer is ready
  2971. (TRUE = -1) or not (FALSE = 0).
  2972.  
  2973. DECLARE FUNCTION PrinTest% (BYVAL Prntr%)
  2974.  
  2975. Specify the printer to be tested as a number between 1 and 4, where 1 =
  2976. LPT1:, 2 = LPT2:, etc. The function will only work with parallel printers.
  2977.  
  2978.  
  2979. PRINTSET
  2980.  
  2981. Most modern printers have a variety of useful styles and fonts which you
  2982. can select by setting dip switches or sending the appropriate control
  2983. codes from the computer. Unfortunately this is not always convenient,
  2984. especially when you are in the middle of a program and have to duck out to
  2985. set up the proper print size. PRINTSET offers a solution to this problem
  2986. in the form of a pull-down menu which allows you to select from a range of
  2987. printer features, using the 'point-and-shoot' method.
  2988.                                                     
  2989. DECLARE SUB PrintSet (BYVAL Row%, BYVAL Col%, BYVAL Attr%, BYVAL Prntr%)
  2990.  
  2991. Where:  Row%     = Row number of the top left-hand corner of the menu
  2992.                    window.
  2993.         Col%     = Column number of the top left-hand corner of the menu
  2994.                    window. 
  2995.         Attr%    = the display attribute or colour which is given to the
  2996.                    menu window.
  2997.         Prntr%   = the printer number (i.e. 1 = LPT1, 2 = LPT2 etc).
  2998.  
  2999. If you supply a value of zero for the Attr% argument, the menu window will
  3000. take the colour or attribute of the character which will be overlaid by
  3001. the top left corner of the window, when it appears. If this character is
  3002. also a single or double-lined horizontal bar (ASCII 196 or 205), the
  3003. border of the menu will be automatically adjusted to blend in with this
  3004. line, allowing you to produce the appearance of a pulldown menu.
  3005.  
  3006. Note:       Although the Toolbox package contains copies of this module
  3007.             configured for different types of printer, only one version
  3008.             of PrintSet may be in the library at any one time.
  3009.  
  3010.             PRINTEPS.OBJ is for Epson printers
  3011.             PRINTIBM.OBJ is for IBM Grahics printers
  3012.             PRINTPRO.OBJ is for IBM Proprinters
  3013.  
  3014.  
  3015. PROGNAME
  3016.  
  3017. Returns the full filespec of the current program.
  3018.  
  3019. DECLARE FUNCTION ProgName$ ()
  3020.  
  3021. DOS appends the full pathname of the currently-executing program to
  3022. the end of the copy of the environment it gives to it. This function
  3023. searches for the pathname string and returns it to the caller.
  3024.  
  3025.  
  3026. RAMDISK
  3027.  
  3028. Many disk-intensive processes, such as file sorting, will run much faster
  3029. when performed on a ramdisk. In such cases, use this function to test if a
  3030. ramdisk is available and the FREESPACE function (above) to see if it has
  3031. enough space for the job required. Don't forget to copy your data back to
  3032. a physical drive afterwards, or you will lose it when you power off.
  3033.  
  3034. RAMDISK searches the system drive table and examines the device driver for
  3035. each block device to see if it is a ramdisk. If one is detected, the
  3036. function returns the ASCII value of the drive letter associated with it
  3037. (eg 68 = D:). If no ramdisk is present, a value of zero is returned. If
  3038. more than one ramdisk is present in the system, only the first one is
  3039. reported on.
  3040.  
  3041. No calling parameters are required.
  3042.  
  3043. DECLARE FUNCTION RamDisk% ()
  3044.  
  3045. RAMDISK will work reliably with all versions of Microsoft's RAMDRIVE and
  3046. IBM's VDISK. However it has not been tested with any of the more esoteric
  3047. virtual disk products, and may not correctly identify some of these.
  3048.  
  3049.  
  3050. RAND
  3051.  
  3052. Returns a random number. This differs from QuickBASIC's RND function in
  3053. that RAND returns an integer and you can specify the range for this value.
  3054.  
  3055. DECLARE FUNCTION Rand% (BYVAL Lower%, BYVAL Higher%)
  3056.  
  3057. Lower% and Higher% are the upper and lower limits for the random number
  3058. to be returned. If Lower% is greater than Higher% then the arguments will
  3059. be transposed.
  3060.  
  3061.  
  3062. REDIRECT
  3063.  
  3064. This routine is intended to be used in conjunction with the QuickBASIC
  3065. SHELL command. It redirects standard output from a shelled program or
  3066. command to the null device, a printer or a file.
  3067.  
  3068. DECLARE SUB ReDirect (BYVAL Switch%, FileSpec$)
  3069.  
  3070. Arguments:  Switch%     The device output is to be directed to
  3071.  
  3072.                     1   the NULL device (output is discarded)
  3073.                     2   the printer device (make sure it's on)
  3074.                     3   the filename specified.
  3075.                     0   turn off redirection
  3076.  
  3077.             FileSpec$   The full pathname (including drive letter if
  3078.                         necessary) of the file to which output should
  3079.                         be redirected. If it does not already exist,
  3080.                         it will be created. Otherwise it will be
  3081.                         truncated to zero length before output begins.
  3082.                         
  3083. Output redirection will only work on child programs and shelled DOS
  3084. commands. QuickBASIC uses its' own output routines and will ignore
  3085. any such device redirection.
  3086.  
  3087.  
  3088. RESEED
  3089.  
  3090. Reinitialises the random number seed used by the RAND function (above).
  3091.  
  3092. DECLARE SUB ReSeed (BYVAL Seed&)
  3093.  
  3094. Note that the argument passed is a LONG integer. This enables you to use
  3095. the value which is returned by the QuickBASIC TIMER function, eg:
  3096.  
  3097.     ReSeed TIMER
  3098.  
  3099. Note that the Toolbox random number seed is not the same as the one used
  3100. internally by QuickBASIC. You cannot, therefore, start a new sequence of
  3101. QB's RND values by using RESEED nor can you use RANDOMIZE to reinitialise
  3102. the sequence for RAND.
  3103.  
  3104.  
  3105. REVINPUT
  3106.  
  3107. Accepts user input in a Reverse Video entry panel, all the usual editing
  3108. keys are supported and entry may be terminated by either a carriage-return
  3109. or one of several special function keys (see below).
  3110.  
  3111. DECLARE FUNCTION RevInput$ (Max%, Visible%, Default$, Legal$, Ctx%, Topic$,_
  3112.                             Mask%, HotKey%)
  3113.  
  3114. Max%         =  maximum number of characters which can be accepted.
  3115. Visible%     =  maximum number of characters which are visible on the
  3116.                 display. If non-zero and less than Max%, this is the
  3117.                 actual size of the data-entry panel.
  3118.     Note:       the data-entry panel will scroll, if necessary, to
  3119.                 ensure that the current character position is always
  3120.                 visible.      
  3121. Default$     =  default string which can be accepted by just pressing
  3122.                 the <Enter> key.
  3123. Legal$       =  a string of legal characters which are acceptable for
  3124.                 input. If a null string is passed then all printable
  3125.                 characters will be accepted. 
  3126. Ctx%         =  set TRUE if context-sensitive help is available, in
  3127.                 which case ... 
  3128. Topic$       =  name of the HELP Topic file to display whenever the
  3129.                 <F1> key is pressed. 
  3130. Mask%        =  if TRUE (non-zero) prevents the characters entered from
  3131.                 being echoed to the display. Instead an asterisk (*) is
  3132.                 displayed for each character position although the entry
  3133.                 string itself is unaffected. Use this for passwords.
  3134. HotKey%      =  If entry is terminated by anything other than the
  3135.                 <Enter> key, this variable will contain an explanatory
  3136.                 return code ..
  3137.  
  3138. Return Codes:   1  =  <Escape> abort entry returning a null string
  3139.                 2  =  <F2>     repeat previous entry for this field
  3140.                 3  =  <Up Arr> pressed, move to previous field 
  3141.                 4  =  <Dn Arr> pressed, move to next field
  3142.                 5  =  <Pg Up>  pressed, move to top of screen
  3143.                 6  =  <Pg Dn>  pressed, move to end of screen
  3144.                 7  =  A hotkey was supplied and used. The calling
  3145.                                program takes appropriate action.
  3146.  
  3147.                 You can specify any key as the hotkey by setting your
  3148.                 own value in HotKey% before calling REVINPUT. This
  3149.                 number can either be the ASCII code of any standard
  3150.                 key or the SCAN code (as a negative value) of one of
  3151.                 the function keys. Set HotKey% to zero to turn off
  3152.                 keyboard trapping (except for keys 1-6 above).            
  3153.  
  3154. Editing Keys:   <L.Arrow>   =  Move cursor one character to the left
  3155.                 <R.Arrow>   =  Move cursor one character to the right
  3156.                 <Home>      =  Move cursor to first character of field
  3157.                 <End>       =  Move cursor to last character of field
  3158.                 <Ctrl End>  =  Clear from current cursor position to
  3159.                                the end of the entry field.
  3160.                 <Insert>    =  Toggle between Insert and Overtype modes
  3161.                 <Delete>    =  Delete character under the cursor.
  3162.                 <BackSpace> =  Replace character under cursor with a
  3163.                                blank space and move cursor one character
  3164.                                to the left.
  3165.                 <F1>        =  pop up on-line HELP screen.
  3166.  
  3167. REVINPUT is designed to be used as part of a full-screen data-entry
  3168. system. Your program can examine the return code to determine whether the
  3169. operator wishes to terminate entry or move forwards or backwards between
  3170. entry fields.
  3171.  
  3172. See also the DATEINPUT function for a keyboard routine specially designed
  3173. to ask the operator for a date!!!!
  3174.  
  3175.  
  3176. ROOTNAME
  3177.  
  3178. Extracts the root filename from a full directory pathname.
  3179.  
  3180. DECLARE FUNCTION RootName$ (Path$, Extension%)
  3181.  
  3182. Path$       the full directory pathname of the file in question. This
  3183.             string can include the drive letter followed by a colon.
  3184.  
  3185. Extension%  If TRUE (non-zero) the returned filename will include the
  3186.             filename extension (if any). If FALSE (zero) the extension
  3187.             part is trimmed off.
  3188.  
  3189.  
  3190. ROUND
  3191.  
  3192. Rounds a double-precision number to the number of decimal places required
  3193. and returns it as a string.
  3194.  
  3195. DECLARE FUNCTION Round$ (Number#, Places%)
  3196.  
  3197.  
  3198. SALUTE
  3199.  
  3200. DECLARE FUNCTION Salute$ (Original$)
  3201.  
  3202. This function strips all but the first and last words from a string
  3203. and capitalises the first letter of each remaining word. This produces
  3204. a string suitable for use as the salutation of a letter.
  3205.  
  3206.  
  3207. SCREENDUMP
  3208.  
  3209. Copies the contents of the current screen (text mode only) to the line
  3210. printer, just as if the operator had pressed the <Prt Scrn> key.
  3211.  
  3212. No calling parameters are required.
  3213.  
  3214. DECLARE SUB ScreenDump ()
  3215.  
  3216. Includes support for 43 and 50-line screens on EGA and VGA adaptors.
  3217.  
  3218. This routine will not work if screen print has previously been disabled by
  3219. a call to the DISABLEPRTSC routine (see above) or if the parallel printer
  3220. at LPT1: is not ready.
  3221.  
  3222.  
  3223. SCREENMODE
  3224.  
  3225. This function calls ROM-BIOS to check the current video mode and then
  3226. converts the returned value to the equivalent QuickBASIC SCREEN number.
  3227. It can detect the Hercules 720 x 348 graphics mode (SCREEN 3) and the new
  3228. Olivetti 640 x 400 mode (SCREEN 4) as well as the Tandy 1000 and PCjr CGA
  3229. modes (SCREENs 5 & 6) which are not supported by QuickBASIC.  Other
  3230. unsupported graphics modes return a value of -1.
  3231.  
  3232. No calling parameters are required.
  3233.  
  3234. DECLARE FUNCTION ScreenMode% ()
  3235.  
  3236.  
  3237. SCREENROWS
  3238.  
  3239. Returns the height of the current screen, in rows, as set by the last
  3240. WIDTH statement (default = 25).
  3241.  
  3242. No calling parameters are required.
  3243.  
  3244. DECLARE FUNCTION ScreenRows% ()
  3245.  
  3246. The number returned may be 25, 43 or 50, depending on the capabilities of
  3247. your display adaptor.
  3248.  
  3249.  
  3250. SCREENWIDTH
  3251.  
  3252. Returns the width of the current screen, in columns, as set by the last
  3253. WIDTH statement.
  3254.  
  3255. No calling parameters are required.
  3256.  
  3257. DECLARE FUNCTION ScreenWidth% ()
  3258.  
  3259. Possible return values are 40 and 80 (default = 80).
  3260.  
  3261.  
  3262. SCRLOCK
  3263.  
  3264. Toggles SCROLL LOCK on or off or, alternatively, reads the current SCROLL
  3265. LOCK key setting.
  3266.  
  3267. DECLARE FUNCTION ScrLock% (BYVAL Switch%)
  3268.  
  3269. Switch% = 0  Turns SCROLL LOCK off
  3270.         = 1  Turns SCROLL LOCK on
  3271.  
  3272. Any other value just returns the current SCROLL status as a logical value
  3273. where -1 (TRUE) means that SCROLL LOCK is on and 0 (FALSE) means that the
  3274. SCROLL LOCK is off.
  3275.  
  3276.  
  3277. SCROLL
  3278.  
  3279. Scrolls the contents of a screen rectangle a specified number of lines or
  3280. columns in the direction indicated, blank spaces of the background colour
  3281. specified are scrolled in to replace them.
  3282.  
  3283. DECLARE SUB Scroll (BYVAL Dir%, BYVAL Y1%, BYVAL X1%, BYVAL Y2%,_
  3284.                     BYVAL X2%, BYVAL Units%, BYVAL Attr%)
  3285.  
  3286. Dir%        =  Scroll direction (0 = down, 1 = up, 2 = left, 3 = right).
  3287. Y1%         =  Top-left row of rectangle to be scrolled.
  3288. X1%         =  Top-left column of rectangle.
  3289. Y2%         =  Bottom-right row of rectangle.
  3290. X2%         =  Bottom-right column of rectangle
  3291. Units%      =  Number of rows or columns to scroll.
  3292. Attr%       =  Display attribute of blank spaces scrolled in.
  3293.  
  3294. Notes:      This routine will work in all graphics modes as well as on
  3295.             the text screen. When scrolling the graphics screen up or
  3296.             down, however, the attribute value must be calculated in a
  3297.             different way:
  3298.  
  3299.             On 320 x 200 4-colour and 640 x 200 2-colour displays the
  3300.             attribute represents a 1-byte pixel pattern, which is
  3301.             equivalent to 8 pixels in 2-colour (SCREEN 2) mode and 4
  3302.             pixels in 4-colour (SCREEN 1) mode. This pixel pattern is
  3303.             replicated through all the blank lines scrolled in.
  3304.  
  3305.             In all other EGA, VGA and MCGA display modes, ATTR% is
  3306.             the colour value for each pixel in the blanked lines.
  3307.  
  3308.             Scrolling sideways in graphics modes, using this routine,
  3309.             does not provide sufficiently fine movement for animation
  3310.             effects, but see the CGASCROLL and MCGASCROLL procedures
  3311.             (above) for a more precise alternative.
  3312.  
  3313.  
  3314. SECURE
  3315.  
  3316. Toggles bit zero of the specified file's directory entry, making it either
  3317. Read-only or Read/Write.
  3318.  
  3319. DECLARE SUB Secure (BYVAL Switch%, FileSpec$)
  3320.  
  3321. If SWITCH% = 1 the file is made Read-only (regardless of whether it can be
  3322. currently written to or not), any other value makes the file Read/Write.
  3323. FILESPEC is the name of the file to be hidden or unhidden. It can include
  3324. a drive letter and directory path but must be an explicit pathname,
  3325. wildcard characters are not allowed.
  3326.  
  3327.  
  3328. SERIALPORTS
  3329.  
  3330. This function checks how many serial ports are available, it does not
  3331. check to see if devices are connected to any of them.
  3332.  
  3333. No calling parameters are required.
  3334.  
  3335. DECLARE FUNCTION SerialPorts% ()
  3336.  
  3337.  
  3338. SETFLAG
  3339.  
  3340. This routine is used to set  one of the sixteen system flags to a value of
  3341. between 0 and 255. These flags are situated in the Intra-Application
  3342. Communications area, an area reserved by DOS for user programs to signal
  3343. to each other. FLAG% is the flag number (1-16), VALUE% is the value you
  3344. want to set.
  3345.  
  3346. DECLARE SUB SetFlag (Flag%, Setting%)
  3347.  
  3348. You can read the current setting of a particular IAC flag byte with the
  3349. GETFLAG function.
  3350.  
  3351.  
  3352. SHARE
  3353.  
  3354. Toggles bit seven of the specified file's directory entry, making it
  3355. either Shareable or Non-shareable. This routine will only work when the
  3356. program which calls it is running under a Novell Network.
  3357.  
  3358. DECLARE SUB Share (BYVAL Switch%, FileSpec$)
  3359.  
  3360. If SWITCH% = 1 the file is made Shareable (regardless of whether it can be
  3361. currently used by other programs or not), any other value makes the file
  3362. Non-shareable. FILESPEC is the name of the file to be shared. It can
  3363. include a drive letter and directory path but must be an explicit
  3364. pathname, wildcard characters are not allowed.
  3365.  
  3366.  
  3367. SHARING
  3368.  
  3369. Reports if SHARE.EXE, the MS-DOS file sharing support module, is installed
  3370. in memory. No calling parameters are required.
  3371.  
  3372. DECLARE FUNCTION Sharing% ()
  3373.  
  3374. If SHARE is installed the function returns a value of -1 (logical TRUE),
  3375. otherwise zero (logical FALSE) is returned.
  3376.  
  3377. Note:   for some reason this function does not return reliable results
  3378.         when called in the QuickBASIC environment, although it works
  3379.         fine in stand-alone programs. Does QB[X] disable SHARE then?
  3380.         
  3381. The NETTEST function (above) returns similar information for file sharing
  3382. under a Novell Network.
  3383.  
  3384.  
  3385. SHUTUP
  3386.  
  3387. Closes the last window opened by the POPUP window procedure (see above)
  3388. and restores the contents of the screen below it.
  3389.  
  3390. DECLARE SUB ShutUp (BYVAL Speed%)
  3391.  
  3392. The Speed% parameter is a delay in milliseconds. If greater than zero
  3393. it produces the effect of imploding the storage buffer contents onto the
  3394. screen, making the window appear to vanish into a point source.
  3395.  
  3396.  
  3397. SORTFILE
  3398.  
  3399. expects the user to supply the name of the file to be sorted. The file,
  3400. itself, must be fixed length and its name can include a drive letter and
  3401. directory pathname. The logical record length of the file must also be
  3402. supplied, along with the start position and length of the field which the
  3403. file is to be sorted on.
  3404.  
  3405. The procedure returns with Done% set to -1 (logical TRUE), if the sort
  3406. completed successfully, or to zero (logical FALSE) if an error occurred.
  3407.  
  3408. DECLARE SUB SortFile (PathName$, OffSet%, FieldLen%, RecordLen%, Done%)
  3409.  
  3410. The program first checks the size of the file and the amount of free disk
  3411. space to see if the it can be sorted in memory, this requires space for
  3412. two copies of the file on disk. If it is too large, the file is sorted in
  3413. place so that no extra disk space is required. Using this method, which is
  3414. far slower, the file may be of any size up to 4 Gigabytes.
  3415.  
  3416. Note:       If, when sorting in place on disk, SORTFILE detects that there
  3417.             is a Ramdisk installed with enough free space to hold the file
  3418.             that is being sorted, the program will copy and sort the file
  3419.             there. This is much faster than a conventional disk sort, but
  3420.             still not as fast as sorting directly in memory.
  3421.  
  3422. Programs calling this routine must have at least two unused file buffers
  3423. available (i.e. no more than thirteen files must be already open).
  3424.  
  3425.  
  3426. SOUNDEX
  3427.  
  3428. Gets the phonetic equivalent of a string. This function returns a long
  3429. integer which represents the 'sound' of a string of text using the SOUNDEX
  3430. phonetic conversion algorithm. It can be used in 'fuzzy' searches, for
  3431. example, to scan a database for an individual when you are not sure of the
  3432. exact spelling of their surname. When searching for SMITH, for instance,
  3433. SOUNDEX would also match SMYTH and SMYTHE.
  3434.  
  3435. DECLARE FUNCTION Soundex& (Text$)
  3436.  
  3437. Note that the initial letter of the search string must exactly match the
  3438. initial letter of the target. GAMMELL and CAMMEL will return different
  3439. values when passed to SOUNDEX. Note also that the function will only
  3440. convert the first word of the string, translation stops at the first
  3441. blank space.
  3442.  
  3443.  
  3444. SPLITNAME
  3445.  
  3446. Parses a string containing the full or postal name of a person and
  3447. extracts the TITLE, INITIALS and SURNAME from it.
  3448.  
  3449. DECLARE SUB SplitName (Source$, Title$, Initial$, SurName$)
  3450.  
  3451. Most commonly used titles (eg MR, MRS, MISS, MS) are correctly
  3452. identified and seperated out.
  3453.  
  3454.  
  3455. SPOOLER
  3456.  
  3457. Gets the installed state of the DOS print spooler, PRINT.COM, so that a
  3458. program can check if it is safe to submit files to the print queue.
  3459.  
  3460. No calling parameters are required.
  3461.  
  3462. DECLARE FUNCTION Spooler% ()
  3463.  
  3464. Returns:    -1  if spooler is installed
  3465.              0  if spooler is not installed
  3466.  
  3467.  
  3468. SPOOLDELETE
  3469.  
  3470. Deletes one or more files from the current print queue.
  3471.  
  3472. FileSpec$ should include the full pathname of the file to be deleted from
  3473. the print queue. It can be ambiguous, using the DOS wildcard characters
  3474. '*' and '?', allowing you to cancel the processing of a range of files
  3475. with a single command.
  3476.  
  3477. DECLARE SUB SpoolDelete (FileSpec$)
  3478.  
  3479. Note:       This function will only work if PRINT.COM, the DOS print
  3480.             spooler has been installed. You can use the SPOOLER
  3481.             function (see above) to check if PRINT.COM is available.
  3482.  
  3483.  
  3484. SPOOLFLUSH
  3485.  
  3486. Deletes all files from the current print queue and terminates output to
  3487. the printer.
  3488.  
  3489. No calling parameters are required.
  3490.  
  3491. DECLARE SUB SpoolFlush ()
  3492.  
  3493. Note:       This function will only work if PRINT.COM, the DOS print
  3494.             spooler has been installed. You can use the SPOOLER
  3495.             function (see above) to check if PRINT.COM is available.
  3496.  
  3497.  
  3498. SPOOLLIST
  3499.  
  3500. Returns the pathname of a file in the current print queue.
  3501.  
  3502. SPOOLLIST can only be used while printing is suspended after a call to the
  3503. SPOOLSUSPEND function (see below) has been made.
  3504.  
  3505. Buffer$ must be preset to a length of at least 64 bytes for the routine to
  3506. work, although you do not have to fill it with spaces first.  When called,
  3507. immediately after printing has been suspended, SPOOLLIST will return, in
  3508. Buffer$, the pathname of the first file in the spooler print queue.
  3509.  
  3510. Further calls will return the names of subsequent files in the queue until
  3511. a string of blank spaces indicates that all entries have been read.
  3512.  
  3513. DECLARE SUB SpoolList (Buffer$)
  3514.  
  3515. The following example demonstrates how SPOOLLIST, SPOOLSUSPEND and
  3516. SPOOLRESTART can be used in a QuickBASIC program.
  3517.  
  3518.     CONST FALSE = 0, TRUE = NOT FALSE
  3519.  
  3520.     Buffer$ = STRING$(64, "*")
  3521.  
  3522.     Status% = SpoolSuspend%
  3523.     PRINT "Spooler suspended, status is"; Status%
  3524.     PRINT "Files in print queue are ...": PRINT
  3525.     Done% = FALSE: Number% = 1
  3526.     DO
  3527.         SpoolList Buffer$
  3528.         IF Buffer$ = SPACE$(64) THEN
  3529.            Done% = TRUE
  3530.         ELSE
  3531.            PRINT Number%, Buffer$
  3532.            Number% = Number% + 1
  3533.        END IF
  3534.     LOOP UNTIL Done%
  3535.     CALL SpoolReStart
  3536. END
  3537.  
  3538. Use SPOOLRESTART (see below) to resume printing after it has been
  3539. suspended for a listing of the queue contents to be made.
  3540.  
  3541. Note:       This function will only work if PRINT.COM, the DOS print
  3542.             spooler has been installed. You can use the SPOOLER
  3543.             function (see above) to check if PRINT.COM is available.
  3544.  
  3545.  
  3546. SPOOLRESTART
  3547.  
  3548. Re-enables output of spooled files to the printer after it has been
  3549. suspended for a status check or for the queue contents to be listed.
  3550.  
  3551. No calling parameters are required.
  3552.  
  3553. DECLARE SUB SpoolReStart ()
  3554.  
  3555. Note:       This function will only work if PRINT.COM, the DOS print
  3556.             spooler has been installed. You can use the SPOOLER
  3557.             function (see above) to check if PRINT.COM is available.
  3558.  
  3559.  
  3560. SPOOLSUBMIT
  3561.  
  3562. Submits a file for processing by the DOS print spooler. 
  3563.  
  3564. FileSpec$ should contain the full pathname of the file to be printed and
  3565. should be no longer than 64 characters. Wildcard characters are not
  3566. allowed. If found, the file will be added to the end of the current print
  3567. queue.
  3568.  
  3569. DECLARE SUB SpoolSubmit (FileSpec$)
  3570.  
  3571. Note:       This function will only work if PRINT.COM, the DOS print
  3572.             spooler has been installed. You can use the SPOOLER
  3573.             function (see above) to check if PRINT.COM is available.
  3574.  
  3575.  
  3576. SPOOLSUSPEND
  3577.  
  3578. Suspends output from the DOS print spooler and reports if an error has
  3579. been encountered. Printing is suspended until you use the SPOOLRESTART
  3580. procedure (see above) to resume output. 
  3581.  
  3582. No calling parameters are required.
  3583.  
  3584. DECLARE FUNCTION SpoolSuspend% ()
  3585.  
  3586. Returns:     0 = no errors
  3587.              1 = invalid function
  3588.              2 = file not found
  3589.              3 = path not found
  3590.              4 = too many open files
  3591.              5 = access denied
  3592.              8 = queue full
  3593.              9 = spooler busy
  3594.             12 = name too long
  3595.             15 = invalid drive    
  3596.  
  3597. SPOOLLIST (see above), which returns the pathnames of files in the print
  3598. queue, can only be called while the spooler is suspended.
  3599.  
  3600. Note:       This function will only work if PRINT.COM, the DOS print
  3601.             spooler has been installed. You can use the SPOOLER
  3602.             function (see above) to check if PRINT.COM is available.
  3603.  
  3604.  
  3605. STATUSLINE
  3606.  
  3607. This procedure displays the message supplied on the bottom line of the
  3608. display, prompts the user for a keypress, waits until it is received and
  3609. then returns, restoring the screen to its former state. The  ASCII value
  3610. of the keypress is returned in the variable that you assign to the
  3611. function.
  3612.  
  3613. DECLARE FUNCTION StatusLine% (Message$)
  3614.  
  3615. Note:       StatusLine will recognise if an EGA or VGA is installed and
  3616.             will correctly locate itself if the screen is in 43 or 50-
  3617.             line mode.
  3618.  
  3619.  
  3620. STRINGSCAN
  3621.  
  3622. This routine searches a variable-length string array for the string
  3623. specified, returning the element number it occupies if found.
  3624.  
  3625. DECLARE FUNCTION StringScan% (Trgt$, BYVAL Size%, BYVAL Strt%, BYVAL Addr%)
  3626.  
  3627. Arguments:  Trgt$ = target string to be searched for.
  3628.             Size% = number of array elements to be searched.
  3629.             Strt% = array element to start searching at.
  3630.             Addr% = address of start element (the VARPTR value).  
  3631.                      
  3632. See also the STRINGSORT routine (below) for a fast method of sorting a
  3633. variable-length string array.
  3634.  
  3635.  
  3636. STRINGSORT
  3637.  
  3638. This procedure can sort a string array into ascending or descending order,
  3639. very quickly indeed.
  3640.  
  3641. DECLARE SUB StringSort (BYVAL Dir%, BYVAL Size%, BYVAL Addr%)
  3642.  
  3643. Arguments:  Dir%    = sort direction (0 = ascending, 1 = descending).
  3644.             Size%   = number of elements to sort.
  3645.             Addr%   = VARPTR of element to start sorting from.
  3646.  
  3647. Note:       This routine now works perfectly with Extended QuickBASIC
  3648.             far string arrays, provided that the range of elements to
  3649.             sort are contained within a single 64K segment. If the
  3650.             array extends over more than one segment then no sorting
  3651.             will be performed at all.
  3652.  
  3653. For an example of fast string sorting and searching, see the source code
  3654. for DEMON, the Toolbox demonstration program.
  3655.  
  3656.  
  3657. STRIPQUOTES
  3658.  
  3659. Strips quotation marks and commas from a string which is to be
  3660. written to a comma-delimited ASCII file.
  3661.  
  3662. DECLARE FUNCTION StripQuote$ (Source$)
  3663.  
  3664. All double quote characters (") found in SOURCE$ are replaced
  3665. with single quotes (') and all commas replaced by blank spaces.
  3666. The length of the string is unchanged.
  3667.  
  3668.  
  3669. STUFFBUFFER
  3670.  
  3671. Stuffs a string of up to fifteen keystrokes into the keyboard typeahead
  3672. buffer. These keystrokes will then be read by subsequent INPUT or INKEY
  3673. statements or passed to DOS when the program ends.
  3674.  
  3675. DECLARE SUB StuffBuffer (Buffer$)
  3676.  
  3677. Buffer$ is the string of ASCII characters to be placed in the keyboard
  3678. buffer. A maximum of fifteen characters may be used, any extra ones will
  3679. be ignored. 
  3680.  
  3681. If the string is a command to be executed by DOS when your program
  3682. terminates, it should include a trailing carriage-return. For example,
  3683. the following command will clear the screen and display a directory
  3684. listing:
  3685.  
  3686. StuffBuffer "CLS" + CHR$(13) + "DIR" + CHR$(13)
  3687.  
  3688. Any previously unread keystrokes will be flushed from the buffer by 
  3689. this routine.
  3690.  
  3691.  
  3692. TEMPFILE
  3693.  
  3694. Creates a temporary file with a user-specified attribute
  3695.  
  3696. DECLARE FUNCTION TempFile$ (BYVAL FlAttr%)
  3697.  
  3698. Argument:   FileAttr%   the directory attribute to be given to the
  3699.                         temporary file. Possible values are:
  3700.                         
  3701.                     0   Normal
  3702.                     1   Read-only
  3703.                     2   Hidden
  3704.                     4   System
  3705.  
  3706. The temporary file is created, with the attribute you specify and a
  3707. unique filename, in the current directory and its full pathname
  3708. (excluding drive letter) is returned by the function. Your program is
  3709. responsible for opening it and all subsequent processing. It will not
  3710. be automatically deleted when the program ends.
  3711.  
  3712.  
  3713. TEXTVAL
  3714.  
  3715. Returns the numeric value of a string of text.
  3716.  
  3717. DECLARE FUNCTION TextVal& (Text$)
  3718.  
  3719. This function takes a string of text and returns a long integer
  3720. which is its numeric equivalent. Only ASCII numerals and letters
  3721. are considered significant and lowercase text evaluates to the same
  3722. values as uppercase.
  3723.  
  3724.  
  3725. ULPRINT
  3726.  
  3727. Sends the text supplied, to the printer, as a string of underlined
  3728. characters.  Output begins at the current print position and can,
  3729. optionally, append a carriage-return/linefeed to take the print head to
  3730. the beginning of a new line when finished.
  3731.  
  3732. DECLARE SUB UlPrint (BYVAL Prntr%, Buffer$, BYVAL NewLine%)
  3733.  
  3734. Arguments:  Prntr%      the parallel port output is to be sent to
  3735.                         (1 = LPT1:, 2 = LPT2:, etc.).
  3736.             Buffer$     the string of text to be printed.
  3737.             NewLine%    set this to a non-zero value if you want 
  3738.                         to move to a new line after printing.
  3739.  
  3740. The routine restores the previous print style or font before it returns
  3741. and does not effect subsequent output to the printer, using the QuickBASIC
  3742. LPRINT or PRINT # statements.
  3743.  
  3744. Note:       The version of this routine stored in the Toolbox
  3745.             library is for EPSON compatible printers. If you have
  3746.             an IBM graphics printer or ProPrinter, then you should
  3747.             rebuild your libraries, using either the PRINTIBM.OBJ
  3748.             or PRINTPRO.OBJ object module in place of PRINTEPS.OBJ.
  3749.  
  3750.  
  3751. UNPAD
  3752.  
  3753. Removes multiple spaces from a string, making sure that no word
  3754. in a string of text has more than one blank space between it.
  3755.  
  3756. DECLARE FUNCTION UnPad$ (Text$, Length%)
  3757.  
  3758. Text$       the string of text to be processed.
  3759.  
  3760. Length%     on return, holds the length of the string after
  3761.             processing.
  3762.  
  3763. Leading and trailing spaces are also trimmed.
  3764.  
  3765.  
  3766. VERIFY
  3767.  
  3768. This function opens a dialogue box, centered at the screen row specified,
  3769. in which is displayed a prompt supplied by the caller. The routine adds a
  3770. further Y/N prompt, and then waits for a keypress. Only <Y/N> responses
  3771. (in upper or lower case) are accepted and the value that is returned
  3772. evaluates to Boolean TRUE (-1), if a Y(es) response was entered, and
  3773. Boolean FALSE (0) if the reply was N(o). The screen is restored to its
  3774. previous state on exit from the function.
  3775.  
  3776. DECLARE FUNCTION Verify% (BYVAL Default%, BYVAL Row%, Prompt$,_
  3777.                           BYVAL Attr%, BYVAL Mouse%)
  3778.  
  3779. DEFAULT%    Specifies the radio button to be highlighted as the default
  3780.             response on entry into the function. Pressing <Return> or
  3781.             clicking the left mouse button without moving the pointer
  3782.             will produce the specified response. If DEFAULT% is set to
  3783.             one the YES button is highlighted. Any other value highlights
  3784.             the NO button. 
  3785.  
  3786. ROW%        The top row of the dialogue box when it is displayed. The
  3787.             box is automatically centered within this row, which may be
  3788.             adjusted so that it remains within the screen boundaries.
  3789.  
  3790. PROMPT$     A string of text comprising the message to be displayed. It
  3791.             must be no longer than 40 characters otherwise it will be
  3792.             truncated to fit inside the display panel.
  3793.  
  3794. ATTR%       The display attribute or colour to be given to the dialogue box.
  3795.             If an argument of zero is supplied, the box is displayed with
  3796.             bright white text on a blue background (colour monitors) or in
  3797.             reverse video (monochrome monitors).
  3798.  
  3799. MOUSE%      should be set to TRUE (-1) or FALSE (0) to indicate if a mouse
  3800.             is installed and can be used to respond.    
  3801.  
  3802. Notes:      The user can respond, either by pressing the <Y> or <N> keys
  3803.             or by using <TAB> to highlight the appropriate radio button
  3804.             and then pressing <RETURN>. 
  3805.  
  3806. Mouse support has now been added, enabling the operator to respond by
  3807. clicking the mouse cursor on the appropriate radio button.
  3808.  
  3809.  
  3810. VERMENU
  3811.  
  3812. Displays and operates a pulldown menu, allowing the user to select from
  3813. the list of options displayed in the menu window. 
  3814.  
  3815. DECLARE SUB VerMenu (Row%, Col%, Attr%, Bdr%, Opts%, Title$, Menu$(),_
  3816.                      Choice%, Nxt%, Bar%, Ctx%, Tpc$, Mouse%, HotKeys%)
  3817.  
  3818. Expects:  Row%, Col%    screen co-ordinates of top-left corner of the
  3819.                         window containing the menu.
  3820.           Attr%         display attribute given to menu window.
  3821.           Bdr%          Border style (1 - 8, 0 = no border). see the
  3822.                         WINDOWS documentation for a list of styles.
  3823.           Opts%         Number of options provided by menu.
  3824.           Title$        Title for the menu, if null string then no
  3825.                         title is displayed.
  3826.           Menu$()       Text for options list. 
  3827.                         MENU$(0) should contain a list of Hotkey
  3828.                         characters, one for each option. Insert a space
  3829.                         at the appropriate position if an option is to
  3830.                         be disabled. A hash character '#' in Menu$(0)
  3831.                         will replace the option at that position with
  3832.                         a horizontal line seperator.
  3833.                         In the remaining option strings an ampersand '&'
  3834.                         indicates that the next character is the Hotkey
  3835.                         to be highlighted for that option. The Hotkey
  3836.                         character should be the same as the one in the
  3837.                         appropriate position of Menu$(0)
  3838.           Ctx%          If set, this indicates that context-sensitive
  3839.                         help is available, in which case ...
  3840.           Tpc$          The root name of the Topic file to be displayed
  3841.                         if the user presses <F1> for help. The current
  3842.                         menu number and selection number are appended to
  3843.                         this to produce the actual filename, eg where:
  3844.                         
  3845.                         Tpc$ = "CONFIG"     Bar% = 2    Choice% = 5
  3846.                         
  3847.                         HELPMATE (see TOOLBOX.DOC) looks for a Topic
  3848.                         file named CONFIG25.HLP.
  3849.  
  3850.                         (Note that Bar% is automatically set if you are
  3851.                         using this function in conjunction with BARMENU.
  3852.                         if not, Bar% defaults to zero and HELMATE expects
  3853.                         CONFIG05.HLP to be the appropriate TOPIC file.)
  3854.                         
  3855.           Mouse%        If set, this flag indicates that a mouse is
  3856.                         installed and can be used to make selections.
  3857.           HotKeys%      If set, this flag allows hotkeys to go directly
  3858.                         to a selection without the user having to press
  3859.                         <ENTER> as well.
  3860.  
  3861. Returns:  Choice%       Number of selection made by user. If zero then
  3862.                         the user pressed <ESC> to abort without making
  3863.                         a selection.
  3864.           Nxt%          Set TRUE if the user pressed the left or right
  3865.                         arrow key to move sideways to another menu, in
  3866.                         which case ....
  3867.           Bar%          is incremented or decremented accordingly.
  3868.  
  3869. The BARMENU procedure provides a similarly featured menu which is
  3870. orientated horizontally.
  3871.  
  3872. See the source code for DEMON.BAS, the Toolbox demonstration program, for
  3873. an example of VERMENU (and BARMENU) in use.
  3874.  
  3875.  
  3876. VGADIM
  3877.  
  3878. Allows a program running on a computer fitted with VGA to dim or brighten
  3879. the display intensity.
  3880.  
  3881. DECLARE SUB VGADim (BYVAL Intensity%)
  3882.  
  3883. Intensity% is a number in the range -63 to +63 which sets the brightness
  3884. of the screen relative to the default value (zero).
  3885.  
  3886.  
  3887. VGALOAD
  3888.  
  3889. Loads EGA, VGA and MCGA screens into video memory from disk. This is an
  3890. alternative to the QuickBASIC BLOAD statement which cannot be used with
  3891. the higher-resolution graphics displays provided by SCREEN modes 7 to 13.
  3892.  
  3893. DECLARE SUB VGALoad (File$)
  3894.  
  3895. FILE$ must be a legal DOS filename, including extension, drive letter and
  3896. directory path where appropriate.
  3897.  
  3898. Note:       The screen image must have been previously written to a disk
  3899.             file using the VGASAVE procedure (see below) and should have
  3900.             the same resolution as that provided by the current SCREEN.
  3901.  
  3902.  
  3903. VGAPAN
  3904.  
  3905. Sets the display window co-ordinates for EGA, VGA and MCGA screens.
  3906.  
  3907. This procedure sets the origins of display window within the video display
  3908. buffer used by the EGA, VGA and MCGA adaptors.  Normally this is at the
  3909. top left-hand corner of the graphics image, but by changing co-ordinates
  3910. you can pan the display through video memory, to create some interesting
  3911. animation effects.
  3912.  
  3913. DECLARE SUB VGAPan (BYVAL X%, BYVAL Y%)
  3914.  
  3915. See the source code to DEMON, the Toolbox demonstration program for an
  3916. example using VGAPAN.
  3917.  
  3918.  
  3919. VGASAVE
  3920.  
  3921. Saves EGA, VGA and MCGA screens from video memory to disk. 
  3922.  
  3923. The normal QuickBASIC BLOAD and BSAVE statements only work properly with
  3924. text and CGA graphics screens. This routine allows you to do the same
  3925. with higher-resolution graphic displays in SCREEN modes 7 to 13.
  3926.  
  3927. DECLARE SUB VGASave (File$)
  3928.  
  3929. FILE$ must be a legal DOS filename, including the extension, drive letter
  3930. and directory path where appropriate.
  3931.  
  3932. A companion procedure, VGALOAD (see above) is provided to allow you to
  3933. retrieve the graphics image from disk, and restore it to the screen.
  3934.  
  3935. See the source code to DEMON, the Toolbox demonstration program for an
  3936. example using VGALOAD and VGASAVE.
  3937.  
  3938.  
  3939. VGATEXT
  3940.  
  3941. Writes characters to the screen in EGA and VGA graphics modes.
  3942.  
  3943. DECLARE SUB VgaText (BYVAL xLoc%, BYVAL yLoc%, Text$,_
  3944.                      BYVAL Attr%, BYVAL Scale%)
  3945.  
  3946. This routine provides a convenient way of displaying text in any of the
  3947. EGA and VGA graphics modes (SCREENs 7-12) without having to bother about
  3948. loading external font files. It uses the standard character definition
  3949. tables built into your display adaptor, but allows you to scale them up to
  3950. eight times normal size and to specify any combination of foreground and
  3951. background colours supported by the current video mode.
  3952.  
  3953. XLOC%       The horizontal co-ordinate of the top left hand pixel
  3954.             from which the text will begin
  3955.  
  3956. YLOC%       The vertical co-ordinate of the top left hand pixel
  3957.             from which the text will begin
  3958.  
  3959. TEXT$       The string of text to be displayed (up to 63 characters).
  3960.  
  3961. ATTR%       The colour (or display attribute in monochrome modes) to
  3962.             be given to the text. This is calculated by the formula:
  3963.  
  3964.             Colour% = (Background% * 256) + Foreground%
  3965.  
  3966.             Foreground and Background values are in the ranges used
  3967.             by the current video mode (eg. 0 - 15 for SCREEN 9). The
  3968.             actual colours displayed depend upon your current PALETTE
  3969.             settings.
  3970.  
  3971.             Note:   supplying a value of -1 for background prevents
  3972.                     background pixels from being changed at all. This
  3973.                     allows text to be blended more naturally into a
  3974.                     complex graphics display.
  3975.  
  3976. SCALE%      The character size of the text to be displayed. This ranges
  3977.             from 1 to 8, where 1 is standard 80-column text (40-column
  3978.             in SCREEN 7) and 8 multiplies the character size by eight
  3979.             on both the horizontal and vertical axes.
  3980.  
  3981. VGATEXT can handle both byte-aligned and non byte-aligned characters. The
  3982. x, y co-ordinates you supply do not need to correspond to a row, column
  3983. character cell in SCREEN 0, the alphanumeric mode. The complete extended
  3984. ASCII character set is supported, including foreign symbols and
  3985. box-drawing characters.
  3986.  
  3987. Since VGATEXT does not support clipping, to ensure a clean display you
  3988. must ensure that the text to be output fits within the current screen
  3989. boundaries.
  3990.  
  3991. See also CGATEXT for displaying characters in SCREEN 1 and MCGATEXT for
  3992. displaying characters in SCREEN 13.
  3993.  
  3994.  
  3995. VIDEOMODE
  3996.  
  3997. Checks the video system capabilities of the host computer.
  3998.  
  3999. DECLARE SUB VideoMode (Colour%, MaxRes%, VideoRam%)
  4000.  
  4001. This function calls ROM-BIOS to check the type of display adaptor which is
  4002. installed in the host system. Three variables are supplied which, on
  4003. return, provide the following information:
  4004.  
  4005. COLOUR%   -1 = Colour adaptor   Indicates the presence of a colour
  4006.            0 = Monochrome       monitor in EGA systems. Returns -1
  4007.                                 for CGA, even if a mono monitor is
  4008.                                 bring used.
  4009. MAXRES%    highest SCREEN       Highest resolution graphics screen
  4010.            resolution           which can be set. Is equivalent to
  4011.                                 QuickBASIC SCREEN numbers. MDA can
  4012.                                 only use SCREEN 0, CGA 0, 1 and 2
  4013.                                 N.B. MaxRes% = 10 indicates an EGA
  4014.                                 with mono monitor. This means that
  4015.                                 SCREEN 9 can NOT be used.
  4016. VIDEORAM%  in kilobytes         Amount of dedicated display memory
  4017.                                 installed. 
  4018.                                 MDA = 4K, CGA = 16K, EGA = 64-256K
  4019.  
  4020.  
  4021. WKDAY
  4022.  
  4023. This function is used to determine the day of the week for a given date.
  4024. It does this by temporarily resetting the system date to the one supplied,
  4025. reading the day from DOS, and then restoring the old date. The weekday is
  4026. returned as a number between 0 and 6, signifying Sunday through Saturday.
  4027.  
  4028. DECLARE FUNCTION WkDay% (BYVAL Dy%, BYVAL Mnth%, BYVAL Yr%)
  4029.  
  4030. Note:   The year value should be supplied as a 4-digit number between
  4031.         1981 and 2099.
  4032.  
  4033. ──────────────────────────────────────────────────────────────────────
  4034.  
  4035. EXTRA ROUTINES FOR QB4
  4036.  
  4037. The following functions and procedures are only included in the version of
  4038. the Toolbox intended for QuickBASIC 4.x and BASIC 6. They are omitted from
  4039. the later version because the Extended QuickBASIC language provided with
  4040. the BASIC 7 Professional Development System includes new statements and
  4041. functions that render them unneccessary. Well they say that imitation IS
  4042. the sincerest form of flattery!
  4043.  
  4044.  
  4045. CHANGEDIR
  4046.  
  4047. This procedure changes the current directory to the one specified by the
  4048. pathname supplied. If a drive letter is included in the argument, the
  4049. routine also changes the current drive.
  4050.  
  4051. DECLARE SUB ChangeDir (PathName$)
  4052.  
  4053. Microsoft have now added CHDIR and CHDRIVE statements to QBX, the new
  4054. Extended QuickBASIC supplied with BASIC 7. Since these statements make
  4055. CHANGEDIR redundant, it is not provided with the BASIC 7 Toolbox.
  4056.  
  4057.  
  4058. FINDFIRST
  4059.  
  4060. This routine sets the Disk Transfer Address to point to a local buffer and
  4061. then attempts to find a match for the file specified in WildCard$. If one
  4062. or more matches are found, the filename of the first matching file (minus
  4063. directory path), is stuffed into the second string argument. If no match
  4064. is found, this string is filled with blank spaces.
  4065.  
  4066. DECLARE SUB FindFirst (Attr%, WildCard$, Match$)
  4067.  
  4068. WildCard$ can contain an ambiguous filename, using the wildcard characters
  4069. * and ?, in which case FINDFIRST will only find the first matching file.
  4070. To obtain the names of any subsequent matches, use the FINDNEXT function
  4071. (see below).
  4072.  
  4073. Match$ must be at least twelve characters long to hold the returning
  4074. filename and extension. You do not need to clear the string first as the
  4075. function does that for you, automatically.
  4076.  
  4077. Normally, only visible files with full read\write access are found, but
  4078. you can extend this to search for hidden, read-only or system files as
  4079. well by setting the Attr% parameter to the appropriate attribute value.
  4080.  
  4081.    Attr% = 0   Visible read\write
  4082.            1   Read-only files
  4083.            2   Hidden files
  4084.            4   System files
  4085.  
  4086. Do not use the FILESIZE function while searching for files with FINDFIRST
  4087. and FINDNEXT. Since both routines relocate the DOS Disk Transfer Address
  4088. during operation, this may lead to a conflict which will cause your
  4089. program to lose track of one or more open files. You should, in any case,
  4090. always use the RESETDTA routine to restore the Disk Transfer Address after
  4091. FINDFIRST/FINDNEXT is completed.
  4092.  
  4093. The DIR$ function which Microsoft have added to Extended QuickBASIC (QBX)
  4094. provides a built-in FINDFIRST/FINDNEXT service which makes the Toolbox
  4095. routines redundant. They are, therefore, omitted from the BASIC 7 version.
  4096.  
  4097.  
  4098. FINDNEXT
  4099.  
  4100. Finds successive matches of an ambiguous filename after a previously
  4101. successful call to FINDFIRST (see above). You can call it repeatedly
  4102. until a blank string is returned in Match$, in which case there are
  4103. no more files to be found.
  4104.  
  4105. DECLARE SUB FindNext (Match$)
  4106.  
  4107. Match$ must be at least twelve characters long to hold the returning
  4108. filename and extension. It does not have to be cleared first, since the
  4109. routine does this for you, automatically.
  4110.  
  4111. Do not make use the FILESIZE function while searching for files with
  4112. FINDFIRST and FINDNEXT. Since both routines relocate the DOS Disk Transfer
  4113. Address during operation, this may lead to a conflict which will cause
  4114. your program to lose track of one or more open files. You should, in any
  4115. case, always use the RESETDTA routine to restore the Disk Transfer Address
  4116. after FINDFIRST/FINDNEXT is completed.
  4117.  
  4118. The DIR$ function which Microsoft have added to Extended QuickBASIC (QBX)
  4119. provides a built-in FINDFIRST/FINDNEXT service which makes the Toolbox
  4120. routines redundant. They are, therefore, omitted from the BASIC 7 version.
  4121.  
  4122.  
  4123. GETDIR
  4124.  
  4125. This procedure writes the pathname of the currently logged directory into
  4126. the string supplied by the caller. The user can specify what drive to
  4127. return the directory for, or default to the current drive.
  4128.  
  4129. DECLARE SUB GetDir (Drive%, Path$)
  4130.  
  4131. This routine expects two arguments to be passed to it. The first is an
  4132. integer which specifies the drive to look at :
  4133.  
  4134. 0 = default drive, 1 = drive A:, 2 = drive B:, etc.
  4135.  
  4136. the second argument is a string which will hold the path of the directory
  4137. returned by DOS. The string must be at least 64 bytes long to hold the
  4138. information. If it were not, the function might overwrite other variables
  4139. in the program data space, with unpredictable results. The returned path-
  4140. name does not include the drive identifier or a leading '\' and is
  4141. terminated by a null (0) byte. if the current directory is the root
  4142. directory, therefore, the first byte of the string will be an ASCII zero,
  4143. not a null string.
  4144.  
  4145. The CURDIR$ function which Microsoft have added to Extended QuickBASIC
  4146. (QBX) allows you to obtain the current directory path and drive, making
  4147. GETDIR redundant. It is, therefore, omitted from the BASIC 7 version of
  4148. the Assembly Language Toolbox.
  4149.  
  4150.  
  4151. GETDRIVE
  4152.  
  4153. This function returns the number of the currently-logged drive.
  4154.  
  4155. No calling parameters are required.
  4156.  
  4157. DECLARE FUNCTION GetDrive% ()
  4158.  
  4159. Values returned are in the series 0 = A:, 1 = B:, 2 = C:, etc.
  4160.  
  4161. The CURDIR$ function which Microsoft have added to Extended QuickBASIC
  4162. (QBX) allows you to obtain the current directory path and drive, making
  4163. GETDRIVE redundant. It is, therefore, omitted from the BASIC 7 version of
  4164. the Assembly Language Toolbox.
  4165.  
  4166.  
  4167. RESETDTA
  4168.  
  4169. This procedure must always be called by your program after the FINDFIRST
  4170. and FINDNEXT functions have been used. It restores the Disk Transfer
  4171. Address to its default value originally set by QuickBASIC.
  4172.  
  4173. No calling parameters are required.
  4174.  
  4175. DECLARE SUB ReSetDTA ()
  4176.  
  4177.  
  4178. SETDRIVE
  4179.  
  4180. This function changes the currently-logged drive to the one specified by
  4181. the calling program (0 = A:, 1 = B:, etc.).
  4182.  
  4183. DECLARE SUB SetDrive (Drive%)
  4184.  
  4185. Since BASIC 7 has now introduced the CHDRIVE statement which performs the
  4186. same task, SETDRIVE is only supported in the version of the Toolbox
  4187. supplied to QuickBASIC 4 users.
  4188.  
  4189. WAITASEC
  4190.  
  4191. System-independent pause for a specified number of seconds. The delay will
  4192. still be the same, whether you have an original IBM-PC or an AT with the
  4193. latest Intel i486 processor running at 66MHz.
  4194.  
  4195. DECLARE SUB WaitaSec (Seconds!)
  4196.  
  4197. This is an alternative to the SLEEP statement, for people who still use
  4198. QuickBASIC 4.0
  4199.  
  4200. ──────────────────────────────────────────────────────────────────────
  4201.  
  4202. ASSEMBLY-LANGUAGE TOOLBOX INTERNAL FUNCTIONS
  4203.  
  4204. The following functions and procedures are used internally by Toolbox
  4205. routines. Assembly-Language programmers may also call them when adding
  4206. routines of their own, provided the appropriate object modules are linked
  4207. to their program at runtime.
  4208.  
  4209.  
  4210. FLAGS
  4211.  
  4212. Sets or gets the current status of individual flags in the Intra-
  4213. Application Communications area (IAC), a 16-byte block of RAM reserved, by
  4214. DOS, for signalling between applications programs.
  4215.  
  4216. Three parameters must be passed on the stack, they are:
  4217.  
  4218.         1)  Switch%     0 = get flag,   1 = set flag
  4219.         2)  Flag%       the offset into the IAC flag table (0 to 15)
  4220.         3)  Setting%    the value to be set into the specified byte
  4221.                         of the flag table (if Switch% = 1).
  4222.  
  4223. This example code fragment sets letter 'A' (ASCII 65) into flag 8 (byte 9)
  4224. of the IAC area.
  4225.  
  4226.             .model  medium              ; Required for QuickBASIC
  4227.  
  4228.             extrn   Flags: far          ; Public name of called routine
  4229.  
  4230.             .code                       ; Define code segment
  4231.  
  4232.             mov     ax,1                ; Set a flag byte
  4233.             push    ax                  ; Pass it on the stack
  4234.             mov     ax,8                ; Flag number 8
  4235.             push    ax                  ; Pass it on the stack
  4236.             mov     ax,'A'              ; Value to set
  4237.             push    ax                  ; Pass it on the stack
  4238.             call    Flags               ; Call the function
  4239.  
  4240. You must still push three parameters onto the stack even if you are only
  4241. reading a flag setting. In this case the third argument will be ignored.
  4242.  
  4243. The setting of the specified IAC flag is returned in the lower byte of the
  4244. AX register (AL). All other registers are preserved.
  4245.  
  4246.  
  4247. GETVERSION
  4248.  
  4249. This function checks the version of DOS under which the host computer is
  4250. currently running.
  4251.  
  4252.             extrn   GetVersion: far
  4253.  
  4254. The following register values may be returned:
  4255.  
  4256.     AL      = Major Version       (MS-DOS 3.2 = 3, etc.)
  4257.     AH      = Minor Version       (MS-DOS 3.2 = 20, etc.) 
  4258.                             
  4259. GETVERSION can be called directly from QuickBASIC, in which case only the
  4260. Major and Minor version numbers returned in AX are available.
  4261.  
  4262. Note:   This function returns the correct version number even under
  4263.         DOS 5.x with SETVER configured to return a different number.
  4264.  
  4265.  
  4266. HIDECURSOR
  4267.  
  4268. Makes the cursor invisible. No parameters are required or returned.
  4269.  
  4270.             extrn   HideCursor: far
  4271.  
  4272. This method ORs the byte value of the cursor start line with 32 (20 Hex)
  4273. which, on all standard video adaptors, turns off the cursor while
  4274. preserving its display characteristics. You can use the SHOWCURSOR
  4275. routine (see below) to restore the cursor to its previous state.
  4276.  
  4277. Note:       HIDECURSOR can be called directly from QuickBASIC but, since
  4278.             the LOCATE statement provides an alternative means of turning
  4279.             off the cursor, it is not necessary.
  4280.  
  4281.  
  4282. SCREENADDRESS
  4283.  
  4284. Calculate screen address from a pair of row/column co-ordinates.
  4285.  
  4286.             extrn   ScreenAddress: far
  4287.  
  4288. Given the row/column column co-ordinate of a character on the screen, this
  4289. function returns the segment:offset address of that character in video
  4290. memory. The address is correctly adjusted to the start of the the
  4291. currently active display page, but no check is made to ensure that the
  4292. co-ordinates supplied are within the actual screen bounds.
  4293.  
  4294. Input:      AL      = Row co-ordinate of character (0 = row 1).
  4295.             AH      = Column co-ordinate of character (0 = column 1).
  4296.  
  4297. Output:     ES:DI==>  Address in video display buffer of the
  4298.                       character cell specified.
  4299.             DX      = CRT status register port address.
  4300.  
  4301. It is assumed that a previous call has been made to the VIDEOTYPE function
  4302. (see below), to determine the screen width, the port address of the CRT
  4303. status register and the correct video display segment. 
  4304.  
  4305.  
  4306. SCREENCOPY
  4307.  
  4308. Copy a character and attribute from the video display to a buffer at the
  4309. address specified.
  4310.  
  4311.             extrn   ScreenCopy: far
  4312.  
  4313. If the 'snow prevention' flag is set, this routine waits until the
  4314. beginning of the next CRT horizontal retrace period before reading data
  4315. from the display. This is necessary only on machines fitted with a Colour
  4316. Graphics Adaptor (CGA) which may suffer from glitches or screen snow if
  4317. data is copied from the screen while the video buffer is being refreshed.
  4318.  
  4319. Input:      DS:SI==>    Address of the screen location from which
  4320.                         the data is to be copied. 
  4321.             ES:DI==>    Address of the buffer into which the data
  4322.                         is to be copied.
  4323.             DX =        Port address of CRT status register.
  4324.  
  4325. Output:     SI and DI   Updated to point to next buffer locations.
  4326.             AX          destroyed.
  4327.  
  4328. It is assumed that a previous call has been made to the VIDEOTYPE function
  4329. (see below), to determine the screen width, the port address of the CRT
  4330. status register and the correct video display segment. VIDEOTYPE also sets
  4331. an internal 'snow-prevention' flag if the host machine has a CGA display
  4332. adaptor installed. This activates a routine which synchronises direct
  4333. video reads and writes to the CRT vertical retrace period, preventing
  4334. interference on the display.
  4335.  
  4336.  
  4337. SCREENREAD
  4338.  
  4339. Read a character and attribute from the display.
  4340.  
  4341.             extrn   ScreenRead: far
  4342.  
  4343. This procedure is similar to SCREENCOPY (see above), except that the word
  4344. is simply loaded into AX instead of being copied into a buffer.
  4345.  
  4346. Input:      DS:SI==>    address, in the video display buffer, from
  4347.                         where the data is to be read
  4348.             DX =        port address of the CRT status register.
  4349.  
  4350. Output:     AL =        character at the specified address
  4351.             AH =        display attribute given to character
  4352.             DI          updated to point to the next word address
  4353.  
  4354. It is assumed that a previous call has been made to the VIDEOTYPE function
  4355. (see below), to determine the screen width, the port address of the CRT
  4356. status register and the correct video display segment. VIDEOTYPE also sets
  4357. an internal 'snow-prevention' flag if the host machine has a CGA display
  4358. adaptor installed. This activates a routine which synchronises direct
  4359. video reads and writes to the CRT vertical retrace period, preventing
  4360. interference on the display.
  4361.  
  4362.  
  4363. SCREENWRITE
  4364.  
  4365. Output a character and attribute to the video display.
  4366.  
  4367.             extrn   ScreenWrite: far
  4368.  
  4369. If the 'snow prevention' flag is set, this routine waits until the
  4370. beginning of the next CRT horizontal retrace period before writing data to
  4371. the display. This is necessary only on machines fitted with a Colour
  4372. Graphics Adaptor (CGA) which may suffer from glitches or screen snow if
  4373. data is written to the screen while the video buffer is being refreshed.
  4374.  
  4375. Input:      ES:DI==>    Address in the video display buffer where
  4376.                         the data is to be written. 
  4377.             DX =        Port address of CRT status register.
  4378.             AL =        Character to output.
  4379.             AH =        Display attribute to set
  4380.  
  4381. Output:     DI          Updated to point to next output address.
  4382.  
  4383. It is assumed that a previous call has been made to the VIDEOTYPE function
  4384. (see below), to determine the screen width, the port address of the CRT
  4385. status register and the correct video display segment. VIDEOTYPE also sets
  4386. an internal 'snow-prevention' flag if the host machine has a CGA display
  4387. adaptor installed. This activates a routine which synchronises direct
  4388. video reads and writes to the CRT vertical retrace period, preventing
  4389. interference on the display.
  4390.  
  4391.  
  4392. SHOWCURSOR
  4393.  
  4394. Makes the cursor visible. No parameters are required or returned.
  4395.  
  4396.             extrn   ShowCursor: far
  4397.  
  4398. This method ANDs the byte value of the cursor start line with 31 (1F Hex)
  4399. which, restores the cursor after being made invisible by the HIDECURSOR
  4400. routine (see above).
  4401.  
  4402. Note:       SHOWCURSOR can be called directly from QuickBASIC but, since
  4403.             the LOCATE statement provides an alternative means of turning
  4404.             the cursor on and off, it is not needed in high-level code.
  4405.  
  4406.  
  4407. VIDEO
  4408.  
  4409. Video equipment check. This function returns information about the active
  4410. display adaptor installed in the host system.
  4411.  
  4412.             extrn   Video: far
  4413.  
  4414. No input parameters are required, on return AX should be examined for the
  4415. following values:
  4416.     
  4417.         AL = type of video adaptor installed
  4418.  
  4419.              1 = MDA   - Monochrome Display Adaptor
  4420.              2 = CGA   - Colour Graphics Adaptor
  4421.              3 = HGC   - Hercules Graphics Card
  4422.              4 = HGC+  - Hercules Graphics Card Plus
  4423.              5 = HIC   - Hercules InColour Card
  4424.              6 = EGA   - Extended Graphics Adaptor
  4425.              7 = PGA   - Professional Graphics Adaptor (IBM PS/2)
  4426.              8 = VGA   - Video Graphics Array
  4427.              9 = MCGA  - MultiColour Graphics Adaptor  (IBM PS/2)
  4428.  
  4429.         AH  (bits 0-6) = size of display memory in 16K blocks
  4430.                          (0 = <16K, 1 = 16K, 2 = 32K, etc.)
  4431.             (bit 7)    = type of display monitor in use
  4432.                          (0 = colour, 1 = monochrome) 
  4433.  
  4434.  
  4435. VIDEOTYPE
  4436.  
  4437. Collects information about the current video display and sets various
  4438. internal flags.
  4439.  
  4440.             extrn   VideoType: far
  4441.  
  4442. The correct video display segment and CRT status port addresses are
  4443. determined for the current system and, if necessary, the internal 'snow'
  4444. prevention flag is set.
  4445.  
  4446. Input:      nothing
  4447.  
  4448. Output:     AL =    Current display mode
  4449.             AH =    Screen width in columns
  4450.             BL =    Screen height in rows
  4451.             BH =    Active display page
  4452.  
  4453. You should make a preliminary call to this function before using any of
  4454. the other internal routines which directly access video memory.
  4455.  
  4456.  
  4457. WRITEBYTE
  4458.  
  4459. Output a byte of data to video memory.
  4460.  
  4461.             extrn   WriteByte: far
  4462.  
  4463. This procedure is similar to ScreenWrite, above, except that only a single
  4464. byte is written. It is used by the BackFill routine to reset the display
  4465. attribute of a character, without changing the character itself.
  4466.  
  4467. Input:      ES:DI==>    address, in the video display buffer, where
  4468.                         the byte is to be written.
  4469.             DX =        port address of the CRT status register.
  4470.             AL =        the byte value to be written.
  4471.  
  4472. Output:     DI          updated to point to the next byte address
  4473.  
  4474. It is assumed that a previous call has been made to the VIDEOTYPE function
  4475. (see above) to determine the screen width, the port address of the CRT
  4476. status register and the correct video display segment. VIDEOTYPE also sets
  4477. an internal 'snow-prevention' flag if the host machine has a CGA display
  4478. adaptor installed. This activates a routine which synchronises direct
  4479. video reads and writes to the CRT vertical retrace period, preventing
  4480. interference on the display.
  4481.  
  4482.  
  4483. ─────────────────────────────────────────────────────────────────────────
  4484. 
  4485.